Atribuição de cobrança ao integrador

Esta página é destinada a integradores parceiros do Vmix Pay. Ela explica como identificar, em cada cobrança criada pela API, de qual integrador a operação se originou — para que o parceiro seja bonificado (revenue-share) sobre aquela cobrança.

O mecanismo é um único campo opcional no corpo da requisição de criação de cobrança: integrador_code.

Onde obter o seu código

O seu código de integrador (formato INTG-XXXXXX) é fornecido pela equipe do Vmix Pay. Ele é público (não é um segredo) — identifica o parceiro, mas não autentica: a autenticação continua sendo o seu access_token Bearer (veja Autenticação).

Como usar

Envie o campo integrador_code no corpo (JSON) da criação da cobrança. Ele é aceito na superfície de criação de cobrança da API pública:

• POST /v1/charges/boleto — boleto (normal ou híbrido)
• POST /v1/charges/pix — cobrança PIX

O campo é opcional. Se você omiti-lo, a cobrança é criada normalmente, sem atribuição a nenhum integrador. Todo o resto do contrato (headers, autenticação, Idempotency-Key, formato de amount) é idêntico ao já documentado em Emitir boleto e na Referência da API (PIX).

Exemplo

O campo integrador_code entra no corpo da emissão do boleto:

curl -X POST https://api.vmixpay.com.br/v1/charges/boleto \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Idempotency-Key: 7d8e9f0a-1b2c-4d3e-8f9a-0b1c2d3e4f5a" \
  -H "Content-Type: application/json" \
  -d '{
    "tipo": "boleto_hibrido",
    "valorCents": "199.90",
    "dataVencimento": "2026-07-15",
    "descricao": "Mensalidade junho",
    "integrador_code": "INTG-A1B2C3",
    "pagador": {
      "nome": "Cliente Exemplo",
      "documento": "00000000000",
      "tipoPessoa": "PESSOA_FISICA",
      "cep": "85000000",
      "cidade": "Guarapuava",
      "logradouro": "Rua Exemplo",
      "numero": "123",
      "uf": "PR"
    }
  }'

Como funciona a atribuição

Quando você envia integrador_code, o Vmix Pay:

1. Resolve o integrador ativo por esse código antes de qualquer gravação. Um código inexistente ou inativo faz a requisição falhar com 400 INTEGRADOR_CODE_INVALID — e nenhuma cobrança é criada (comportamento anti-órfã: ou a cobrança nasce já atribuída corretamente, ou não nasce).
2. Carimba o integrador na cobrança de forma imutável. A atribuição é definida no momento da criação e não pode ser alterada depois. A bonificação (revenue-share) é calculada sobre as cobranças atribuídas ao seu código.

A atribuição entra na Idempotency-Key

O integrador_code faz parte da assinatura da requisição idempotente. Reenviar a mesma Idempotency-Key com um integrador_code diferente é tratado como conflito e retorna 409 IDEMPOTENCY_KEY_REUSED. Use uma Idempotency-Key nova para cada cobrança distinta.

Só a API de integrador atribui

A atribuição ao integrador acontece exclusivamente por este campo na API pública de criação de cobrança. Cobranças criadas por outras superfícies (painel do lojista, carnê/recorrência) não são atribuídas a um integrador.

Erros

Erro	Quando
400 INTEGRADOR_CODE_INVALID	integrador_code inexistente ou inativo — nenhuma cobrança é criada.
409 IDEMPOTENCY_KEY_REUSED	Mesma Idempotency-Key reenviada com um integrador_code diferente (ou qualquer outro campo do corpo diferente).

Os demais erros de criação de cobrança (autenticação, scope, amount/Idempotency-Key) seguem o já documentado em Emitir boleto e Erros & Idempotência.