Integrações de pagamento

Conecte Woovi, AbacatePay ou Stripe e emita a NFS-e automaticamente a cada pagamento confirmado.

Conecte a conta da sua plataforma de pagamento à Corvo. Quando um pagamento é confirmado, a Corvo emite a NFS-e pelo mesmo caminho da API: valida a empresa e o certificado, consome um crédito do plano e envia a nota à prefeitura.

Como funciona

Você cria uma conexão (POST /v1/integrations/connections) e recebe o webhookUrl dela.
Cadastre esse endereço no painel da plataforma de pagamento. A plataforma passa a avisar a Corvo a cada pagamento.
A Corvo confere a autenticação do aviso, guarda o evento e responde na hora. O processamento acontece em segundo plano.
Se o pagamento está confirmado e existe uma regra de serviço, a nota é emitida. A competência é a data da confirmação (fuso de São Paulo).
O mesmo pagamento nunca gera duas notas, mesmo que a plataforma reenvie o aviso.

Rotas

Método	Rota	Descrição
GET	`/v1/integrations/providers`	Plataformas disponíveis e os campos de credencial de cada uma
POST	`/v1/integrations/connections`	Criar uma conexão
GET	`/v1/integrations/connections`	Listar conexões
GET	`/v1/integrations/connections/:id`	Consultar uma conexão
POST	`/v1/integrations/connections/:id/validate`	Conferir as credenciais e identificar a conta
POST	`/v1/integrations/connections/:id/activate`	Começar a emitir automaticamente
POST	`/v1/integrations/connections/:id/pause`	Parar de emitir; os eventos continuam sendo guardados
POST	`/v1/integrations/connections/:id/disconnect`	Desconectar de vez
GET	`/v1/integrations/connections/:id/rules`	Consultar as regras de serviço
PUT	`/v1/integrations/connections/:id/rules`	Substituir as regras de serviço
GET	`/v1/integrations/connections/:id/events`	Eventos recebidos
GET	`/v1/integrations/connections/:id/operations`	Vendas e o estado da nota de cada uma
PATCH	`/v1/integrations/operations/:id/customer`	Completar o tomador de uma venda pendente
POST	`/v1/integrations/operations/:id/retry`	Tentar emitir de novo
POST	`/v1/integrations/inbound/:publicId`	Endereço que a plataforma de pagamento chama (público, autenticado pelo conector)

As rotas administrativas exigem integrations.view (consultar) ou integrations.manage (criar, ativar, alterar regras). Chaves de API full_access têm as duas.

Conectar uma conta

1. Criar a conexão

curl -X POST "$BASE_URL/v1/integrations/connections"   -H "X-API-Key: $CORVO_API_KEY"   -H "Content-Type: application/json"   -d '{
    "provider": "woovi",
    "companyId": "<id da empresa>",
    "environment": "test",
    "credentials": {},
    "activeFrom": "2026-11-01T00:00:00Z"
  }'

2. Definir a regra de serviço e ativar

curl -X PUT "$BASE_URL/v1/integrations/connections/$CONNECTION_ID/rules"   -H "X-API-Key: $CORVO_API_KEY"   -H "Content-Type: application/json"   -d '{ "rules": [ { "service": { "code": "010101", "description": "Consultoria" }, "sendEmail": true } ] }'

curl -X POST "$BASE_URL/v1/integrations/connections/$CONNECTION_ID/validate" -H "X-API-Key: $CORVO_API_KEY"
curl -X POST "$BASE_URL/v1/integrations/connections/$CONNECTION_ID/activate" -H "X-API-Key: $CORVO_API_KEY"

Uma regra sem externalProductId vale para qualquer produto. Para dar um serviço diferente a um produto, envie outra regra com o externalProductId dele. Pagamentos anteriores a activeFrom são ignorados. Com allowAnonymousCustomer: true, a nota sai sem tomador quando o pagamento não traz CPF/CNPJ.

Por plataforma

Woovi

Não há credencial para informar: envie "credentials": {}. A Corvo gera o webhookToken e o devolve em secrets.webhookToken só na resposta da criação. O ambiente test usa o sandbox da Woovi e live usa a conta de produção.
Na Woovi, crie um webhook com o webhookUrl da conexão e o evento de cobrança paga (OPENPIX:CHARGE_COMPLETED). Em Cabeçalhos HTTP, adicione o cabeçalho Authorization com o webhookToken no campo Valor.
O tomador da nota é o cliente da cobrança, nunca quem pagou o Pix.
Cada cobrança vira uma nota, identificada pelo correlationID. A descrição do serviço na nota é o comment da cobrança; sem ele, vale o padrão da empresa.
Reembolso: marque também PIX_TRANSACTION_REFUND_SENT_CONFIRMED no webhook. A Corvo liga o reembolso à venda pelo endToEndId do Pix. Reembolso parcial é ignorado.

AbacatePay

Credencial: apiKey, uma chave de API v2 da AbacatePay (Integração > API > + Nova chave) com as permissões CUSTOMER:READ e PRODUCT:READ. A Corvo gera o webhookSecret e devolve o webhookUrl já com ?webhookSecret=... só na resposta da criação. Guarde esse endereço.
Na AbacatePay, crie um webhook: cole o webhookUrl na URL e o secrets.webhookSecret (devolvido só na criação) no campo Secret, e marque checkout.completed e transparent.completed. A Corvo aceita a assinatura Standard Webhooks (webhook-id, webhook-timestamp, webhook-signature) e o formato antigo (?webhookSecret=).
O devMode do evento precisa bater com o ambiente da conexão: eventos de teste não emitem nota em uma conexão live, e o inverso também.
O webhook traz o CPF/CNPJ mascarado, então a Corvo consulta o cliente na AbacatePay com a sua chave e usa o documento completo. Se o cliente não tiver documento, a venda fica pendente (customer_tax_id_missing) ou sai sem tomador se a regra tiver allowAnonymousCustomer.
O externalProductId das regras é o id do item do checkout. A descrição do serviço na nota é o nome do produto (a Corvo o consulta pela chave); sem a permissão PRODUCT:READ, vale o padrão da empresa.
Reembolso: marque também checkout.refunded e transparent.refunded no webhook. Sem o cancelamento automático, o reembolso ou a contestação depois da nota abre a pendência refund_after_invoice e a nota não é cancelada.

Vendas que precisam de atenção

Quando uma venda não pode virar nota sozinha, ela fica visível em GET /v1/integrations/connections/:id/operations com fiscalStatus e blockReason.

blockReason	O que fazer
`customer_tax_id_missing`	A plataforma não enviou CPF/CNPJ completo. Informe com `PATCH /v1/integrations/operations/:id/customer` e use `POST /v1/integrations/operations/:id/retry`.
`no_rule` / `ambiguous_rule`	Crie ou ajuste as regras e use `retry`.
`invoice_rejected`	A validação fiscal recusou o pedido. A mensagem explica o campo; corrija e use `retry`.
`quota_exceeded`	Sem créditos ou limite do plano. Depois de resolver, use `retry`.
`connection_inactive`	A conexão está pausada ou precisa de nova autorização. Reative e use `retry`.
`company_not_ready`	A empresa não está pronta ou o certificado está ausente, vencido ou inválido. Corrija o cadastro e use `retry`.
`before_active_from`	O pagamento é anterior à data de início da conexão. Nenhuma nota é emitida.
`refunded` / `disputed`	O pagamento foi reembolsado ou contestado antes da nota. Nenhuma nota é emitida.
`refund_after_invoice`	Reembolso ou contestação chegou depois da nota e o cancelamento automático está desligado. A nota continua autorizada. Para cancelar, use `POST /v1/invoices/:id/cancel`; para os próximos reembolsos, ligue `cancelOnRefund` na regra (contestação nunca cancela).
`cancel_requested`	Nada a fazer: a Corvo pediu o cancelamento da nota (motivo "Cancelado por reembolso"). Acompanhe o resultado na página da nota.
`cancel_failed`	Não foi possível pedir o cancelamento (por exemplo, a nota está num estado que não permite). Veja a nota e, se puder cancelar, use `retry`.

Por padrão, reembolso ou contestação não cancela a nota. Para cancelar sozinho no reembolso, envie "cancelOnRefund": true na regra: a Corvo pede o cancelamento com o motivo "Cancelado por reembolso" (o crédito da nota não volta). Contestação nunca cancela. Para cancelar manualmente, use POST /v1/invoices/:id/cancel.

O ambiente (test ou live) é definido na conexão. Se a plataforma informar que o evento é de outro ambiente, a Corvo descarta o evento e não emite nota.