Autenticação

Toda chamada M2M usa uma API Key no header x-api-key. Cada chave é vinculada a um tenant e a uma lista de escopos (features habilitadas) — a mesma chave nunca pode agir em nome de outro tenant, e só acessa a feature contracts se esse escopo tiver sido concedido a ela.

Para solicitar uma chave, peça a um admin AppsToB para gerá-la em Integrações → Tenants & Tokens — o valor é mostrado uma única vez no momento da criação (não é recuperável depois). O tenantId enviado no body abaixo deve ser exatamente o tenant ao qual a sua chave está vinculada.

Enviar contrato para assinatura

POST /v1/contracts/send

Gera o documento a partir de um template cadastrado no painel admin, substitui as variáveis e envia para assinatura eletrônica via D4Sign. O contrato é criado de forma assíncrona — a resposta traz um contractLogId para acompanhamento.

Requisição em multipart/form-data (não JSON), para suportar anexos binários. Os campos signatories, variables e observers vão como texto contendo JSON serializado.

Papéis de signatário (signatories[].role):

Desde a sessão 87, role é o próprio código act da D4Sign (como string, ex.: "role":"4") — não um nome semântico nosso. A D4Sign suporta 13 códigos nativamente; o AppsToB hoje habilita 7 — enviar um código não habilitado (mesmo que exista na D4Sign) resulta em 400. Linhas verdes = habilitado.

Precisa de um código ainda não habilitado ("2", "3", "6", "7", "8" ou "9")? Fale com a AppsToB — é decisão de negócio habilitar novos códigos, não uma limitação técnica da D4Sign. Lista completa e fonte oficial: docs/reference/D4SIGN_API.md.

Exemplo — variables:

{"RAZAO_SOCIAL":"Empresa LTDA","CNPJ_CPF":"12.345.678/0001-99"}

As chaves de variables devem corresponder exatamente aos placeholders do template (fieldsUsed, consultável via GET /api/admin/contracts/templates/:id no painel admin) — nenhuma pode faltar, nenhuma extra é aceita.

[
  { "name": "João Silva", "email": "joao@empresa.com.br" }
]

[
  { "name": "João Silva",      "email": "joao@empresa.com.br",     "role": "1" },
  { "name": "Maria Fiadora",   "email": "maria@empresa.com.br",    "role": "10" },
  { "name": "Pedro Testemunha","email": "pedro@empresa.com.br",    "role": "5" }
]

// signatories
[
  { "name": "João Silva",    "email": "joao@empresa.com.br",  "role": "1" },
  { "name": "Maria Fiadora", "email": "maria@empresa.com.br", "role": "10" }
]

// observers (campo separado, mesmo padrão de string JSON serializada)
[
  { "email": "gerente@empresa.com.br", "permission": 1 }
]

[
  { "name": "João Silva",  "email": "joao@empresa.com.br",  "role": "1" },
  { "name": "Carla Sócia", "email": "carla@empresa.com.br", "role": "11" }
]

Requisição completa (multipart)

Junta tudo — header, campos de texto e anexo — como o request realmente sai na rede. Sem observers:

curl -X POST https://ia.appstob.com.br/v1/contracts/send \
  -H "x-api-key: SUA_CHAVE_AQUI" \
  -F "templateId=550e8400-e29b-41d4-a716-446655440000" \
  -F "tenantId=estore-prod" \
  -F 'signatories=[{"name":"João Silva","email":"joao@empresa.com.br","role":"1"},{"name":"Maria Fiadora","email":"maria@empresa.com.br","role":"10"}]' \
  -F 'variables={"RAZAO_SOCIAL":"Empresa LTDA","CNPJ_CPF":"12.345.678/0001-99"}' \
  -F "attachments=@pedido_de_compra.pdf"

Mesmo exemplo, agora com observers (linha extra, resto idêntico):

curl -X POST https://ia.appstob.com.br/v1/contracts/send \
  -H "x-api-key: SUA_CHAVE_AQUI" \
  -F "templateId=550e8400-e29b-41d4-a716-446655440000" \
  -F "tenantId=estore-prod" \
  -F 'signatories=[{"name":"João Silva","email":"joao@empresa.com.br","role":"1"},{"name":"Maria Fiadora","email":"maria@empresa.com.br","role":"10"}]' \
  -F 'variables={"RAZAO_SOCIAL":"Empresa LTDA","CNPJ_CPF":"12.345.678/0001-99"}' \
  -F 'observers=[{"email":"gerente@empresa.com.br","permission":1}]' \
  -F "attachments=@pedido_de_compra.pdf"

N anexos: repita -F "attachments=@..." uma vez por arquivo — mesmo nome de campo, um -F por parte. Limite de 5 anexos por envio, 50MB por arquivo — passar de qualquer um dos dois retorna 400 com mensagem explicando qual limite foi excedido.

Anexo maior que 50MB? Compacte do seu lado antes de enviar (o limite é o teto real de upload da própria D4Sign — não é uma restrição arbitrária nossa). Não fazemos compactação automática hoje.

curl -X POST https://ia.appstob.com.br/v1/contracts/send \
  -H "x-api-key: SUA_CHAVE_AQUI" \
  -F "templateId=550e8400-e29b-41d4-a716-446655440000" \
  -F "tenantId=estore-prod" \
  -F 'signatories=[{"name":"João Silva","email":"joao@empresa.com.br","role":"1"}]' \
  -F 'variables={"RAZAO_SOCIAL":"Empresa LTDA","CNPJ_CPF":"12.345.678/0001-99"}' \
  -F "attachments=@pedido_de_compra.pdf" \
  -F "attachments=@nota_fiscal.pdf" \
  -F "attachments=@comprovante_endereco.jpg"

Respostas

202 — aceito, envio em andamento

HTTP/1.1 202 Accepted

{
  "contractLogId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "status": "pending"
}

400 — payload inválido / variables não corresponde ao template

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Template \"Contrato de Compra\" — variables inválidas (faltando: CNPJ_CPF (CNPJ / CPF)).",
    "detail": {
      "templateName": "Contrato de Compra",
      "missingFields": [{ "key": "CNPJ_CPF", "label": "CNPJ / CPF" }],
      "unknownFields": [],
      "forbiddenFields": []
    }
  }
}

401 — API key ausente/inválida, ou sem o escopo contracts

HTTP/1.1 401 Unauthorized

{
  "error": { "message": "API key inválida ou ausente.", "type": "unauthorized" }
}

403 — tenantId do body não é o tenant da sua API key

HTTP/1.1 403 Forbidden

{
  "error": {
    "code": "TENANT_MISMATCH",
    "message": "Esta API key está vinculada ao tenant \"estore-prod\" — não pode operar em nome de \"outro-tenant\"."
  }
}

422 — erro na geração/envio (template inativo, falha na D4Sign)

HTTP/1.1 422 Unprocessable Entity

{
  "error": { "code": "CONTRACT_ERROR", "message": "Template não encontrado ou inativo" }
}

Webhook de confirmação de assinatura

POST /v1/contracts/webhook

Endpoint que a D4Sign chama para notificar eventos (signed, cancelled). Não requer API Key — a autenticação é via HMAC SHA-256 no header Content-Hmac, calculado como SHA256(uuid_document + secret).

Este endpoint sempre retorna 200 para eventos conhecidos, mesmo em caso de erro interno, para evitar retentativas desnecessárias da D4Sign. Retorna 401 apenas quando o HMAC é inválido.

Spec OpenAPI completa (todos os campos, exemplos e schemas): docs/openapi-public.yaml.