Português

1. Contexto

A DeRE (Declaração de Regimes Específicos) é a obrigação acessória do IBS e da CBS para os regimes específicos: financeiro, seguros, planos de saúde e afins. A plataforma Brinta recebe os dados que a empresa já tem, transforma em eventos da DeRE, gera o XML assinado e transmite ao fisco.

Este guia cobre o módulo transacional: como enviar cada operação à Brinta via API, uma a uma ou em lote. A Brinta agrupa as operações, gera a chave e o sequencial de cada uma, monta o evento correto e transmite.

2. Eventos transacionais e codBC

Cada operação é informada em um único evento, definido pelo seu código de base de cálculo (codBC), Tabela 12 da DeRE. Na API, o codBC vai no campo code das linhas de IBS e CBS (seção 4.3). O cliente não escolhe o evento: a Brinta o determina a partir do codBC.

Como os prazos são curtos (5 ou 7 dias), recomendamos enviar as operações à Brinta diariamente ou de forma contínua.

3. Duas formas de envio

Base URL: https://api.brinta.com. Autenticação: Authorization: Bearer <token>.

4. Estrutura de uma transação DeRE

Exemplo de uma operação de arranjo de pagamento (codBC 2405, evento D-2241), com POST /sales/:

{
  "invoice_date": "2026-10-09T15:42:44.847Z",
  "transaction_owner_company_id": "b52692d8-6dde-49b2-ad58-b8cc068c1b80",
  "transaction_external_id": "ABC3595695",
  "currency": "BRL",
  "type": "sale",
  "use_tax_engine": false,
  "status": "completed",
  "buyer": {
    "name": "CLIENTE SERVICOS LTDA",
    "type": "business",
    "address": {
      "address_line_1": "AV DAS NAÇÕES UNIDAS 14171",
      "address_line_2": "ANDAR 19 E 20 EDIF ROCHAVERA",
      "city": "Sao Paulo",
      "state": "BR-SP",
      "country": "BR",
      "municipal_code": "3550308"
    },
    "tax_registrations": [
      {
        "number": "05.577.323/0001-38",
        "type": "CNPJ",
        "status": "Lucro real",
        "level": "country",
        "location": "BR"
      }
    ]
  },
  "items": [
    {
      "name": "DeRE transaction",
      "amount": 10000,
      "categories": [
        { "list": "DeRE type", "code": "DeRE" }
      ],
      "taxes": [
        {
          "name": "ISS", "type": "ISS", "description": "Imposto sobre Serviços",
          "level": "country", "location": "BR",
          "rate": 0.02, "rate_type": "percentage",
          "taxable_amount": 10000, "amount": 200,
          "adds_to_final_amount": false
        },
        {
          "name": "ISS Outro", "type": "ISS", "description": "Imposto sobre Serviços",
          "level": "country", "location": "BR",
          "rate": 0.02, "rate_type": "percentage",
          "taxable_amount": 10000, "amount": 200,
          "adds_to_final_amount": false
        },
        {
          "name": "PIS", "type": "PIS", "description": "Programa de Integração Social",
          "level": "country", "location": "BR",
          "rate": 0.0065, "rate_type": "percentage",
          "taxable_amount": 10000, "amount": 65,
          "adds_to_final_amount": false
        },
        {
          "name": "COFINS", "type": "COFINS",
          "description": "Contribuição para o Financiamento da Seguridade Social",
          "level": "country", "location": "BR",
          "rate": 0.03, "rate_type": "percentage",
          "taxable_amount": 10000, "amount": 300,
          "adds_to_final_amount": false
        },
        {
          "name": "IBS", "type": "VAT", "code": "2405",
          "description": "Imposto sobre Bens e Serviços",
          "level": "state", "location": "BR",
          "rate": 0.001, "rate_type": "percentage",
          "taxable_amount": 9235, "amount": 9.24,
          "adds_to_final_amount": false
        },
        {
          "name": "IBS", "type": "VAT", "code": "2405",
          "description": "Imposto sobre Bens e Serviços",
          "level": "municipality", "location": "BR",
          "rate": 0.001, "rate_type": "percentage",
          "taxable_amount": 9235, "amount": 9.24,
          "adds_to_final_amount": false
        },
        {
          "name": "CBS", "type": "VAT", "code": "2405",
          "description": "Contribuição sobre Bens e Serviços",
          "level": "country", "location": "BR",
          "rate": 0.009, "rate_type": "percentage",
          "taxable_amount": 9235, "amount": 83.12,
          "adds_to_final_amount": false
        }
      ]
    }
  ]
}

Outros tributos da operação (CSLL, IRRF etc.) podem ir no mesmo array taxes, com o mesmo formato. Eles não entram na DeRE.

4.1 Campos do cabeçalho

4.2 Categoria DeRE type

Em cada item, sempre com o mesmo valor:

"categories": [ { "list": "DeRE type", "code": "DeRE" } ]

Ela marca a operação como transação DeRE. O evento de destino é definido pelo codBC (seção 4.3), não pela categoria.

4.3 Tributos IBS e CBS

• code é o codBC (4 dígitos, Tabela 12) e é obrigatório nas três linhas. Ele define o evento DeRE da operação (seção 2).
• O IBS vai em duas linhas, uma por esfera: state e municipality (city também é aceito). Não envie um IBS único consolidado.
• taxable_amount é a base de cálculo do IBS/CBS (vBCApur): o valor da operação menos os tributos que não integram a base (ISS e PIS/COFINS) e as deduções permitidas. No exemplo: 10.000 − (200 + 200 + 65 + 300) = 9.235.
• rate vai em decimal (0.001 = 0,1%). A Brinta converte para o percentual da DeRE.
• amount é o tributo: taxable_amount × rate, arredondado a 2 casas.

4.4 Do JSON ao evento DeRE

A Brinta gera o resto: CNPJ raiz do declarante (nrInsc, a partir de transaction_owner_company_id), chave e sequencial do agrupamento (chAgrup, seq), período, subperíodo, finalidade do evento e assinatura.

4.5 Dados adicionais por evento

Alguns eventos pedem dados além dos campos acima. A Brinta orienta o envio de cada um durante a implementação, conforme os codBC em que a sua empresa opera.

Exemplo de buyer com physical_address, beneficiaries[] e senders[]:

"buyer": {
  "name": "CLIENTE SERVICOS LTDA",
  "type": "business",
  "address": { "...": "endereço cadastral do adquirente" },
  "physical_address": {
    "address_line_1": "RUA AUGUSTA 1500",
    "city": "Sao Paulo",
    "state": "BR-SP",
    "country": "BR",
    "municipal_code": "3550308"
  },
  "tax_registrations": [ { "...": "..." } ]
},
"beneficiaries": [
  {
    "company": {
      "name": "MARIA SILVA",
      "type": "person",
      "role_external": "titular",
      "date_of_birth": "1985-04-23",
      "address": { "country": "BR", "municipal_code": "3550308" },
      "tax_registrations": [
        { "number": "12345678909", "type": "CPF", "level": "country", "location": "BR" }
      ]
    }
  }
],
"senders": [
  {
    "company": {
      "name": "CORRETORA PONTO DE VENDA LTDA",
      "type": "business",
      "role_external": "ponto de venda",
      "address": { "country": "BR" },
      "tax_registrations": [
        { "number": "12345678000195", "type": "CNPJ", "level": "country", "location": "BR" }
      ]
    }
  }
]

5. use_tax_engine: tributos prontos ou recalculados

Na Batch API o motor de cálculo nunca roda: os tributos devem vir prontos em cada item, como em use_tax_engine: false. Se o cliente precisa que a Brinta recalcule o IBS/CBS, use a API unitária.

6. Validação do adquirente (Tax ID Validation)

A DeRE identifica cada adquirente por CPF ou CNPJ e município. Para evitar rejeições, o cliente pode validar o adquirente antes de enviar as operações, com a API de Tax ID Validation da Brinta. Ela consulta a fonte oficial e devolve, para CPF, nome e situação cadastral e, para CNPJ, razão social, situação cadastral, CNAE e endereço.

curl -X POST https://api.brinta.com/tax-id-validations/ \
  -H "Authorization: Bearer $BRINTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": ["BR"],
    "company": {
      "type": "business",
      "tax_registration": {
        "number": "05577323000138",
        "type": "CNPJ",
        "level": "country",
        "location": "BR"
      }
    }
  }'

• A validação é assíncrona: o POST devolve {id, status: "in_process"} e o resultado sai em GET /tax-id-validations/{id} ou por webhook.
• Se o adquirente já estiver cadastrado como empresa na Brinta, valide com company_id (ou company_external_id) e "update_company": true: os dados oficiais ficam gravados e podem ser referenciados como buyer nas transações.
• Também é possível validar dentro da própria transação, enviando "tax_id_validation": true no buyer. Essa opção precisa ser habilitada pela Brinta para a sua empresa.

Guia: https://docs.brinta.com/docs/tax-id-validation-how-to · Brasil (CPF e CNPJ): https://docs.brinta.com/reference/tax-id-validation-brazil

7. Envio unitário (API REST)

curl -X POST https://api.brinta.com/sales/ \
  -H "Authorization: Bearer $BRINTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @transacao.json

A resposta traz a transação criada (ou os erros de validação). Para consultar depois: GET /sales/{id}.

Estornos e cancelamentos: POST /refunds/, referenciando a venda original com original_transaction_external_id (seu ID) ou original_transaction_id (ID Brinta), nunca os dois. O estorno pode ser total, parcial por valor ou por item. A Brinta gera a referência à operação original no evento (chAgrupRef, seqRef).

8. Envio em lote (Batch API)

Para volume, envie até 10.000 operações por request com POST /transaction-batches/ e "transaction_type": "sale". Cada elemento de transactions tem o mesmo corpo do POST /sales/ da seção 4, com a categoria DeRE type e o codBC em code nas linhas de IBS e CBS. Um mesmo lote pode misturar operações de codBC (e eventos) diferentes.

{
  "transaction_type": "sale",
  "transactions": [
    { "transaction_external_id": "ABC3595695", "...": "mesmo corpo da seção 4" },
    { "transaction_external_id": "ABC3595696", "...": "mesmo corpo da seção 4" }
  ]
}

O lote é assíncrono, com resultado por operação, e nunca roda o motor de cálculo (seção 5). Idempotência, acompanhamento, correção de erros, estornos e limites estão no guia da Batch API: https://docs.brinta.com/docs/batch-transactions

9. Checklist antes de produção

• Empresa declarante cadastrada na Brinta, com D-1001 e D-1011 ativos.
• codBC de cada tipo de operação identificado (Tabela 12) e, com isso, os eventos que se aplicam.
• Dados adicionais dos eventos aplicáveis (seção 4.5) combinados com a Brinta.
• Categoria DeRE type = DeRE em todos os itens.
• IBS em duas linhas (state e municipality) e CBS em country, todas com o codBC em code.
• Decidido use_tax_engine (false se o IBS/CBS já vem calculado).
• Adquirentes validados com Tax ID Validation (recomendado).
• Canal escolhido: API unitária, Batch API ou ambos, com envio diário ou contínuo.
• Lote de teste validado com dry_run: true.

Mais detalhes da Batch API: https://docs.brinta.com/docs/batch-transactions

English

1. Context

DeRE (Declaração de Regimes Específicos) is the IBS and CBS reporting obligation for Brazil's specific regimes: financial services, insurance, health plans and similar. The Brinta platform takes the data the company already has, turns it into DeRE events, generates the signed XML and transmits it to the tax authority.

This guide covers the transactional module: how to send each operation to Brinta through the API, one by one or in batches. Brinta groups the operations, generates each one's key and sequence number, builds the right event and transmits it.

2. Transactional events and codBC

Each operation is reported in exactly one event, set by its tax base code (codBC), DeRE Table 12. In the API, the codBC goes in the code field of the IBS and CBS lines (section 4.3). The client does not pick the event: Brinta derives it from the codBC.

Deadlines are short (5 or 7 days), so we recommend sending operations to Brinta daily or continuously.

3. Two ways to send

Base URL: https://api.brinta.com. Authentication: Authorization: Bearer <token>.

4. Structure of a DeRE transaction

See the full example (a payment arrangement operation, codBC 2405, event D-2241) in section 4 of the Portuguese version. The payload is identical.

Other taxes on the operation (CSLL, IRRF, etc.) can go in the same taxes array, in the same format. They are not part of DeRE.

4.1 Header fields

4.2 DeRE type category

On every item, always with the same value:

"categories": [ { "list": "DeRE type", "code": "DeRE" } ]

It flags the operation as a DeRE transaction. The target event is set by the codBC (section 4.3), not by the category.

4.3 IBS and CBS taxes

• code is the codBC (4 digits, Table 12) and is required on all three lines. It sets the operation's DeRE event (section 2).
• IBS is sent as two lines, one per level: state and municipality (city is also accepted). Do not send a single consolidated IBS line.
• taxable_amount is the IBS/CBS tax base (vBCApur): the operation value minus the taxes that are not part of the base (ISS and PIS/COFINS) and the allowed deductions. In the example: 10,000 − (200 + 200 + 65 + 300) = 9,235.
• rate is a decimal (0.001 = 0.1%). Brinta converts it to the DeRE percentage.
• amount is the tax: taxable_amount × rate, rounded to 2 decimals.

4.4 From JSON to DeRE event

Brinta generates the rest: the declarant's root CNPJ (nrInsc, from transaction_owner_company_id), grouping key and sequence (chAgrup, seq), period, sub-period, event purpose and signature.

4.5 Additional data per event

Some events require data beyond the fields above. Brinta guides how to send each one during implementation, based on the codBC your company operates under.

See the physical_address, beneficiaries[] and senders[] example in section 4.5 of the Portuguese version.

5. use_tax_engine: ready-made or recalculated taxes

The Batch API never runs the tax engine: taxes must come ready on each item, as with use_tax_engine: false. If the client needs Brinta to recalculate IBS/CBS, use the single-transaction API.

6. Buyer validation (Tax ID Validation)

DeRE identifies each buyer by CPF or CNPJ and municipality. To avoid rejections, the client can validate the buyer before sending operations, with Brinta's Tax ID Validation API. It queries the official source and returns, for a CPF, the name and registration status and, for a CNPJ, the corporate name, registration status, CNAE and address.

curl -X POST https://api.brinta.com/tax-id-validations/ \
  -H "Authorization: Bearer $BRINTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": ["BR"],
    "company": {
      "type": "business",
      "tax_registration": {
        "number": "05577323000138",
        "type": "CNPJ",
        "level": "country",
        "location": "BR"
      }
    }
  }'

• Validation is asynchronous: the POST returns {id, status: "in_process"} and the result comes from GET /tax-id-validations/{id} or a webhook.
• If the buyer is already a company in Brinta, validate with company_id (or company_external_id) and "update_company": true: the official data is stored and can be referenced as buyer in transactions.
• You can also validate inside the transaction itself by sending "tax_id_validation": true on buyer. Brinta has to enable this option for your company.

Guide: https://docs.brinta.com/docs/tax-id-validation-how-to · Brazil (CPF and CNPJ): https://docs.brinta.com/reference/tax-id-validation-brazil

7. Single sending (REST API)

curl -X POST https://api.brinta.com/sales/ \
  -H "Authorization: Bearer $BRINTA_TOKEN" \
  -H "Content-Type: application/json" \
  -d @transaction.json

The response returns the created transaction (or the validation errors). To look it up later: GET /sales/{id}.

Refunds and cancellations: POST /refunds/, referencing the original sale with original_transaction_external_id (your ID) or original_transaction_id (Brinta ID), never both. A refund can be total, partial by amount, or per item. Brinta generates the reference to the original operation in the event (chAgrupRef, seqRef).

8. Batch sending (Batch API)

For volume, send up to 10,000 operations per request with POST /transaction-batches/ and "transaction_type": "sale". Each element of transactions has the same body as POST /sales/ in section 4, with the DeRE type category and the codBC in code on the IBS and CBS lines. One batch can mix operations with different codBC (and events).

{
  "transaction_type": "sale",
  "transactions": [
    { "transaction_external_id": "ABC3595695", "...": "same body as section 4" },
    { "transaction_external_id": "ABC3595696", "...": "same body as section 4" }
  ]
}

Batches are asynchronous, return a result per operation, and never run the tax engine (section 5). Idempotency, tracking, fixing errors, refunds and limits are covered in the Batch API guide: https://docs.brinta.com/docs/batch-transactions

9. Go-live checklist

• Declaring company set up in Brinta, with D-1001 and D-1011 active.
• codBC identified for each operation type (Table 12), and with it the events that apply.
• Additional data for the applicable events (section 4.5) agreed with Brinta.
• DeRE type category = DeRE on every item.
• IBS as two lines (state and municipality) and CBS as country, all with the codBC in code.
• use_tax_engine decided (false if IBS/CBS already comes calculated).
• Buyers validated with Tax ID Validation (recommended).
• Channel chosen: single API, Batch API, or both, sending daily or continuously.
• Test batch validated with dry_run: true.

More on the Batch API: https://docs.brinta.com/docs/batch-transactions