Contas de Faturamento

Gerenciamento de contas de faturamento (Billing Accounts) para cobrança de clientes.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/billing/api/v1/billing-accounts`	Criar conta de faturamento	`BILLING_ACCOUNTS_CREATE`
GET	`/billing/api/v1/billing-accounts`	Listar contas	`BILLING_ACCOUNTS_READ`
GET	`/billing/api/v1/billing-accounts/:id`	Obter conta por ID	`BILLING_ACCOUNTS_READ`
PATCH	`/billing/api/v1/billing-accounts/:id`	Atualizar conta	`BILLING_ACCOUNTS_UPDATE`
DELETE	`/billing/api/v1/billing-accounts/:id`	Excluir conta	`BILLING_ACCOUNTS_DELETE`

Atributos

Campo	Tipo	Descrição
`personId`	string (UUID)	ID da pessoa associada (opcional)
`name`	string	Nome da conta de faturamento
`email`	string	E-mail principal para contato
`status`	enum	Status: `ACTIVE`, `SUSPENDED`, `CLOSED`
`balance`	number	Saldo atual da conta
`currency`	string	Moeda (ex: `BRL`, `USD`)
`billingEmail`	string	E-mail para envio de faturas (opcional)
`billingAddress`	object	Endereço de cobrança
`taxId`	string	CPF/CNPJ ou outro documento fiscal
`taxIdType`	string	Tipo do documento (ex: `CPF`, `CNPJ`)
`createdAt`	datetime	Data de criação
`updatedAt`	datetime	Data da última atualização

Estrutura do Endereço (billingAddress)

Campo	Tipo	Descrição
`street`	string	Logradouro
`number`	string	Número
`city`	string	Cidade
`state`	string	Estado/UF
`zipCode`	string	CEP
`country`	string	País

Criar Conta de Faturamento

POST /api/v1/billing-accounts

Cria uma nova conta de faturamento.

Atributos

Campo	Tipo	Obrigatório	Descrição
`personId`	string	Não	ID da pessoa associada
`name`	string	Sim	Nome da conta
`email`	string	Sim	E-mail principal
`status`	enum	Não	Status inicial (padrão: `ACTIVE`)
`currency`	string	Não	Moeda (padrão: configuração da organização)
`billingEmail`	string	Não	E-mail para faturas
`billingAddress`	object	Não	Endereço de cobrança
`taxId`	string	Não	CPF/CNPJ
`taxIdType`	string	Não	Tipo do documento

cURL
JavaScript

curl -X POST 'https://billing.stg.catalisa.app/billing/api/v1/billing-accounts' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "billing-accounts",
      "attributes": {
        "name": "Empresa ABC Ltda",
        "email": "financeiro@empresa-abc.com.br",
        "currency": "BRL",
        "taxId": "12.345.678/0001-90",
        "taxIdType": "CNPJ",
        "billingAddress": {
          "street": "Av. Paulista",
          "number": "1000",
          "city": "São Paulo",
          "state": "SP",
          "zipCode": "01310-100",
          "country": "Brasil"
        }
      }
    }
  }'

const response = await fetch('https://billing.stg.catalisa.app/billing/api/v1/billing-accounts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'billing-accounts',
      attributes: {
        name: 'Empresa ABC Ltda',
        email: 'financeiro@empresa-abc.com.br',
        currency: 'BRL',
        taxId: '12.345.678/0001-90',
        taxIdType: 'CNPJ',
        billingAddress: {
          street: 'Av. Paulista',
          number: '1000',
          city: 'São Paulo',
          state: 'SP',
          zipCode: '01310-100',
          country: 'Brasil',
        },
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Conta criada: ${data.id}`);

Response (201 Created)

{
  "data": {
    "type": "billing-accounts",
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "links": {
      "self": "/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010"
    },
    "attributes": {
      "name": "Empresa ABC Ltda",
      "email": "financeiro@empresa-abc.com.br",
      "status": "ACTIVE",
      "balance": 0,
      "currency": "BRL",
      "taxId": "12.345.678/0001-90",
      "taxIdType": "CNPJ",
      "billingAddress": {
        "street": "Av. Paulista",
        "number": "1000",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "01310-100",
        "country": "Brasil"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010"
  }
}

Listar Contas de Faturamento

GET /api/v1/billing-accounts

Lista todas as contas de faturamento com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[status]`	enum	Filtrar por status
`filter[personId]`	UUID	Filtrar por pessoa associada

cURL
JavaScript

curl 'https://billing.stg.catalisa.app/billing/api/v1/billing-accounts?filter[status]=ACTIVE&page[size]=10' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[status]': 'ACTIVE',
  'page[size]': '10',
});

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/billing-accounts?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta, links } = await response.json();
console.log(`Total de contas: ${meta.totalItems}`);

Response (200 OK)

{
  "data": [
    {
      "type": "billing-accounts",
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "links": {
        "self": "/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010"
      },
      "attributes": {
        "name": "Empresa ABC Ltda",
        "email": "financeiro@empresa-abc.com.br",
        "status": "ACTIVE",
        "balance": 1500.00,
        "currency": "BRL",
        "taxId": "12.345.678/0001-90",
        "taxIdType": "CNPJ",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 25,
    "totalPages": 3,
    "currentPage": 1,
    "itemsPerPage": 10
  },
  "links": {
    "self": "/api/v1/billing-accounts?page[number]=1&page[size]=10",
    "next": "/api/v1/billing-accounts?page[number]=2&page[size]=10",
    "last": "/api/v1/billing-accounts?page[number]=3&page[size]=10"
  }
}

Obter Conta por ID

GET /api/v1/billing-accounts/:id

Obtém os detalhes de uma conta de faturamento específica.

cURL
JavaScript

curl 'https://billing.stg.catalisa.app/billing/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010' \
  -H 'Authorization: Bearer SEU_TOKEN'

const accountId = '550e8400-e29b-41d4-a716-446655440010';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/billing-accounts/${accountId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
console.log(`Saldo: ${data.attributes.currency} ${data.attributes.balance}`);

Response (200 OK)

{
  "data": {
    "type": "billing-accounts",
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "links": {
      "self": "/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010"
    },
    "attributes": {
      "name": "Empresa ABC Ltda",
      "email": "financeiro@empresa-abc.com.br",
      "status": "ACTIVE",
      "balance": 1500.00,
      "currency": "BRL",
      "taxId": "12.345.678/0001-90",
      "taxIdType": "CNPJ",
      "billingAddress": {
        "street": "Av. Paulista",
        "number": "1000",
        "city": "São Paulo",
        "state": "SP",
        "zipCode": "01310-100",
        "country": "Brasil"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  },
  "links": {
    "self": "/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010"
  }
}

Atualizar Conta

PATCH /api/v1/billing-accounts/:id

Atualiza os dados de uma conta de faturamento.

Atributos Atualizáveis

Campo	Tipo	Descrição
`name`	string	Nome da conta
`email`	string	E-mail principal
`status`	enum	Status da conta
`billingEmail`	string	E-mail para faturas
`billingAddress`	object	Endereço de cobrança
`taxId`	string	CPF/CNPJ
`taxIdType`	string	Tipo do documento

cURL
JavaScript

curl -X PATCH 'https://billing.stg.catalisa.app/billing/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "data": {
      "type": "billing-accounts",
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "attributes": {
        "billingEmail": "faturamento@empresa-abc.com.br",
        "status": "SUSPENDED"
      }
    }
  }'

const accountId = '550e8400-e29b-41d4-a716-446655440010';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/billing-accounts/${accountId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    data: {
      type: 'billing-accounts',
      id: accountId,
      attributes: {
        billingEmail: 'faturamento@empresa-abc.com.br',
        status: 'SUSPENDED',
      },
    },
  }),
});

const { data } = await response.json();
console.log(`Status atualizado: ${data.attributes.status}`);

Response (200 OK)

{
  "data": {
    "type": "billing-accounts",
    "id": "550e8400-e29b-41d4-a716-446655440010",
    "links": {
      "self": "/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010"
    },
    "attributes": {
      "name": "Empresa ABC Ltda",
      "email": "financeiro@empresa-abc.com.br",
      "billingEmail": "faturamento@empresa-abc.com.br",
      "status": "SUSPENDED",
      "balance": 1500.00,
      "currency": "BRL",
      "taxId": "12.345.678/0001-90",
      "taxIdType": "CNPJ",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T11:00:00Z"
    }
  },
  "links": {
    "self": "/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010"
  }
}

Excluir Conta

DELETE /api/v1/billing-accounts/:id

Remove uma conta de faturamento. A conta não pode ter assinaturas ativas ou faturas pendentes.

cURL
JavaScript

curl -X DELETE 'https://billing.stg.catalisa.app/billing/api/v1/billing-accounts/550e8400-e29b-41d4-a716-446655440010' \
  -H 'Authorization: Bearer SEU_TOKEN'

const accountId = '550e8400-e29b-41d4-a716-446655440010';

const response = await fetch(`https://billing.stg.catalisa.app/billing/api/v1/billing-accounts/${accountId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

if (response.status === 204) {
  console.log('Conta excluída com sucesso');
}

Response (204 No Content)

Sem corpo de resposta.

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	Dados inválidos (e-mail, taxId, etc.)
404	`NOT_FOUND`	Conta não encontrada
409	`CONFLICT`	E-mail já cadastrado em outra conta
409	`CONFLICT`	Conta possui assinaturas ativas (exclusão)
409	`CONFLICT`	Conta possui faturas pendentes (exclusão)

Endpoints​

Atributos​

Estrutura do Endereço (billingAddress)​

Criar Conta de Faturamento​

Atributos​

Response (201 Created)​

Listar Contas de Faturamento​

Query Parameters​

Response (200 OK)​

Obter Conta por ID​

Response (200 OK)​

Atualizar Conta​

Atributos Atualizáveis​

Response (200 OK)​

Excluir Conta​

Response (204 No Content)​

Erros Comuns​

Endpoints

Atributos

Estrutura do Endereço (billingAddress)

Criar Conta de Faturamento

Atributos

Response (201 Created)

Listar Contas de Faturamento

Query Parameters

Response (200 OK)

Obter Conta por ID

Response (200 OK)

Atualizar Conta

Atributos Atualizáveis

Response (200 OK)

Excluir Conta

Response (204 No Content)

Erros Comuns