Campos comuns (cabeçalho, buyer, Batch API, Tax ID Validation): guia geral.

Português

1. Quando se aplica

Evento	Operações	Prazo
D-3201	Contraprestações de planos de saúde humana, de animais domésticos e de assistência funerária, e comissões de administradoras de benefícios	7 dias após cada bloco de 7 dias

2. codBC

codBC	Descrição
5010	Planos de assistência à saúde humana
5020	Planos de assistência à saúde de animais domésticos
5030	Planos de assistência funerária
5050	Administração de benefícios de planos de assistência à saúde

A modalidade autogestão (5040) não gera evento transacional.

3. Tipo de contrato

O tipo de contrato (tpContrato) define quem é o buyer e quais dados de beneficiários são exigidos. Envie-o em items[].categories[] com list = "DeRE tpContrato".

`tpContrato`	Contrato	`buyer`	Titulares (`beneficiaries[]`)	Valor por titular (`amount`)	Data de nascimento do titular	Entidade relacionada (`senders[]`)
1	Individual ou familiar	O próprio titular	Não enviar	Não	Não	Não
2	Coletivo sem administradora de benefícios	A empresa contratante	Obrigatório (CPF)	Obrigatório	Não	Não
3	Coletivo com administradora de benefícios	A empresa contratante	Obrigatório (CPF)	Obrigatório	Não	Obrigatório
4	Sem valor definido por usuário	A empresa contratante	Obrigatório (CPF)	Não	Obrigatório	Não

4. Campos específicos

Campo DeRE	Envio na API
`idContrato` (número do contrato ou apólice)	`items[].external_item_id`
`vOper` (contraprestação recebida; para administradora de benefícios, a comissão recebida)	`items[].amount`
`vBCApur`	`taxable_amount` das linhas de IBS e CBS
Titular (`CPFTitular`, `dtNascTitular`) e valor do titular com seus dependentes (`vTitularDep`)	`beneficiaries[].company`, com `role_external` = `policyholder` e `date_of_birth`, e `beneficiaries[].amount`
Dependentes (`dtNascDep`)	`beneficiaries[].company.participants[]`, com `role_external` = `dependent` e `date_of_birth`
`CNPJEntidRelac` (a outra entidade do contrato coletivo administrado: operadora ou administradora)	`senders[].company`, com `role_external` = `related_entity`

5. Exemplo: plano coletivo com administradora de benefícios

Operadora de saúde humana (codBC 5010), contrato coletivo com administradora (tpContrato = 3).

{
  "transaction_owner_company_id": "b52692d8-6dde-49b2-ad58-b8cc068c1b80",
  "transaction_external_id": "SAUDE-CTR2026000123-2026-10",
  "invoice_date": "2026-10-09T15:42:44.847Z",
  "currency": "BRL",
  "type": "sale",
  "status": "completed",
  "use_tax_engine": false,
  "buyer": {
    "name": "INDUSTRIA EXEMPLO SA",
    "type": "business",
    "address": { "country": "BR", "state": "BR-SP", "city": "Sao Paulo", "municipality_code": "3550308" },
    "tax_registrations": [ { "number": "12345678000195", "type": "CNPJ", "level": "country", "location": "BR" } ]
  },
  "beneficiaries": [
    {
      "amount": 1500,
      "company": {
        "name": "MARIA SILVA", "type": "person", "role_external": "policyholder",
        "address": { "country": "BR", "municipality_code": "3550308" },
        "tax_registrations": [ { "number": "12345678909", "type": "CPF", "level": "country", "location": "BR" } ],
        "participants": [
          { "type": "person", "role_external": "dependent", "date_of_birth": "2015-08-10" },
          { "type": "person", "role_external": "dependent", "date_of_birth": "2018-02-03" }
        ]
      }
    },
    {
      "amount": 700,
      "company": {
        "name": "PEDRO ALVES", "type": "person", "role_external": "policyholder",
        "address": { "country": "BR", "municipality_code": "3509502" },
        "tax_registrations": [ { "number": "98765432100", "type": "CPF", "level": "country", "location": "BR" } ]
      }
    }
  ],
  "senders": [
    {
      "company": {
        "name": "ADMINISTRADORA DE BENEFICIOS EXEMPLO LTDA", "type": "business", "role_external": "related_entity",
        "address": { "country": "BR" },
        "tax_registrations": [ { "number": "11222333000144", "type": "CNPJ", "level": "country", "location": "BR" } ]
      }
    }
  ],
  "items": [
    {
      "name": "Mensalidade plano coletivo outubro",
      "external_item_id": "CTR2026000123",
      "amount": 2200,
      "categories": [
        { "list": "DeRE type", "code": "DeRE" },
        { "list": "DeRE tpContrato", "code": "3" }
      ],
      "taxes": [
        { "name": "IBS", "type": "VAT", "code": "5010", "level": "state", "location": "BR", "rate": 0.001, "rate_type": "percentage", "taxable_amount": 2200, "amount": 2.2, "adds_to_final_amount": false },
        { "name": "IBS", "type": "VAT", "code": "5010", "level": "municipality", "location": "BR", "rate": 0.001, "rate_type": "percentage", "taxable_amount": 2200, "amount": 2.2, "adds_to_final_amount": false },
        { "name": "CBS", "type": "VAT", "code": "5010", "level": "country", "location": "BR", "rate": 0.009, "rate_type": "percentage", "taxable_amount": 2200, "amount": 19.8, "adds_to_final_amount": false }
      ]
    }
  ]
}

O valor de cada titular inclui os seus dependentes: 1.500 + 700 = 2.200.
Para tpContrato = 2, o mesmo JSON sem senders[].
Para tpContrato = 4, os titulares levam date_of_birth e não levam amount.
Para tpContrato = 1, não envie beneficiaries[]: o buyer é o titular.

English

1. When it applies

Event	Operations	Deadline
D-3201	Payments for human health, pet health and funeral assistance plans, and benefits administrator commissions	7 days after each 7-day block

2. codBC

See the table in section 2 of the Portuguese version. Self-managed plans (5040) do not generate a transactional event.

3. Contract type

The contract type (tpContrato) sets who the buyer is and which beneficiary data is required. Send it in items[].categories[] with list = "DeRE tpContrato".

`tpContrato`	Contract	`buyer`	Primary beneficiaries (`beneficiaries[]`)	Amount per primary beneficiary (`amount`)	Primary beneficiary's birth date	Related entity (`senders[]`)
1	Individual or family	The primary beneficiary	Do not send	No	No	No
2	Group without a benefits administrator	The contracting company	Required (CPF)	Required	No	No
3	Group with a benefits administrator	The contracting company	Required (CPF)	Required	No	Required
4	No amount defined per user	The contracting company	Required (CPF)	No	Required	No

4. Specific fields

DeRE field	API field
`idContrato` (contract or policy number)	`items[].external_item_id`
`vOper` (payment received; for a benefits administrator, the commission received)	`items[].amount`
`vBCApur`	`taxable_amount` of the IBS and CBS lines
Primary beneficiary (`CPFTitular`, `dtNascTitular`) and amount for the primary beneficiary with dependents (`vTitularDep`)	`beneficiaries[].company`, with `role_external` = `policyholder` and `date_of_birth`, and `beneficiaries[].amount`
Dependents (`dtNascDep`)	`beneficiaries[].company.participants[]`, with `role_external` = `dependent` and `date_of_birth`
`CNPJEntidRelac` (the other entity of the managed group contract: health plan operator or administrator)	`senders[].company`, with `role_external` = `related_entity`

5. Example: group plan with a benefits administrator

See the JSON in section 5 of the Portuguese version. codBC 5010, tpContrato = 3.

Each primary beneficiary's amount includes their dependents: 1,500 + 700 = 2,200.
For tpContrato = 2, the same JSON without senders[].
For tpContrato = 4, primary beneficiaries carry date_of_birth and no amount.
For tpContrato = 1, do not send beneficiaries[]: the buyer is the primary beneficiary.