Pagadoria e certidões
Contrato curto para um sistema externo usar o Garagem como backoffice de pós-venda. A negociação e as pessoas continuam na API de negociações. Esta página não cria cobrança nem dispara repasse: isso fica na interface, porque o payload leva CPF e dados bancários.
Autenticação: a mesma API key de Configurações → Desenvolvedor.
Authorization: Bearer sua_api_keyA chave age com o perfil de quem a criou.
- Ler pagamentos exige Pagamentos → Visualizar.
- Montar o carrinho de certidões e emitir exige perfil proprietário ou administrador.
Valores de certidão e de pagamento vêm em centavos (amountMinor), moeda BRL. Não mande CPF, banco ou chave PIX nestes endpoints. A resposta também não devolve esses campos.
O que já está no MCP
Seção intitulada “O que já está no MCP”POST /api/mcp com a mesma API key (ou OAuth) já expõe estas ferramentas. Elas não estão no catálogo certidoes.* da interface. O catálogo público é o conjunto com expose: mcp.
| Ferramenta | O que faz |
|---|---|
payments.list_payments | Lista cobranças sem documento, banco ou PIX |
payments.get_payment | Uma cobrança, mesmo recorte |
payments.list_rental_invoices | Faturas de aluguel |
subscription.get_distribution_status | Status do repasse, destino mascarado |
subscription.preview_distribution_split | Prévia do split, sem disparar transferência |
certificate.browse_catalog | Catálogo com preço do servidor e aplicabilidade |
certificate.resolve_parties | Partes do negócio, só nome e papel |
certificate.get_cart | Carrinho com total e versionToken |
certificate.get_order_status | Status por item |
certificate.add_cart_item | Inclui item no rascunho |
certificate.remove_cart_item | Remove item (exige versionToken) |
certificate.submit_order | Emite e gasta o total. Reenvio não pede de novo |
certificate.retry_item | Reemite um item com correção, também pago |
certificate.list_deal_orders | Lista pedidos de um negócio, só id e status |
transaction.get_diligence_loop | Leitura da diligência |
transaction.list_diligences | Lista diligências |
transaction.start_diligence_process | Abre o processo de diligência |
transaction.resolve_diligence_finding | Resolve um apontamento tipado |
transaction.contest_diligence_finding | Contesta um apontamento |
transaction.retry_diligence_processing | Reprocessa coleta ou análise que falhou |
Incluir item, emitir e retentar são recusados quando a conexão MCP está vinculada a um agente. Com API key de proprietário ou administrador, a chamada passa. Soltar o repasse para a conta do recebedor não está no MCP.
A API REST é esse mesmo procedimento. HTTP e MCP executam a operação portátil.
Pagadoria
Seção intitulada “Pagadoria”Não há POST /payments. Criar a cobrança e liberar o repasse continuam na interface.
GET /api/v1/payments| Parâmetro | Tipo | Descrição |
|---|---|---|
dealId | string | Filtra pela negociação |
listingId | uuid | Filtra pelo anúncio |
status | string | pending, processing, paid, partial, failed, cancelled, refunded |
paymentType | string | sale ou rent |
limit | number | Default 50, máximo 100 |
curl "https://app.garagem.ai/api/v1/payments?dealId=DEAL_ID&status=paid" \ -H "Authorization: Bearer sua_api_key"Cada item traz id, status, paymentType, paymentMethod, totais (totalAmount, serviceFee, netAmount, paidAmount), parcelas, e a referência de negociação e anúncio (id e code).
Ler uma
Seção intitulada “Ler uma”GET /api/v1/payments/{id}found: false quando o id não existe ou está fora do alcance. Não é um 404.
Certidões
Seção intitulada “Certidões”A pessoa, a empresa e o imóvel já precisam estar na negociação. Estes endpoints não recebem CPF, endereço nem nome da mãe. Eles usam o que já está gravado.
1. Partes
Seção intitulada “1. Partes”POST /api/v1/certificates/parties{ "dealId": "uuid-da-negociacao" }roster[].partyId é o entityId do passo 3. displayName é nome de exibição. Documento, contato e endereço não vêm.
2. Catálogo
Seção intitulada “2. Catálogo”POST /api/v1/certificates/catalog{ "dealId": "uuid-da-negociacao", "region": "SP", "certificateKeys": ["rf_pessoa_fisica"]}region e certificateKeys são opcionais. Use certificates[].key como certificateType. applicability[].applicable diz se aquela parte pode pedir aquela certidão. price.amountMinor é o preço do servidor, em centavos.
3. Incluir no carrinho
Seção intitulada “3. Incluir no carrinho”POST /api/v1/certificates/cart/items{ "dealId": "uuid-da-negociacao", "certificateType": "rf_pessoa_fisica", "entityId": "party-id"}A resposta traz orderId, itemId e o carrinho. outcome: "not_applicable" significa que a certidão não cabe naquela parte. O primeiro item cria o rascunho.
Para tirar um item do rascunho:
POST /api/v1/certificates/cart/items/remove{ "orderId": "id-do-pedido", "itemId": "id-do-item", "versionToken": "token-lido-no-carrinho"}version_conflict pede para reler o carrinho e tentar de novo.
4. Ler o carrinho
Seção intitulada “4. Ler o carrinho”GET /api/v1/certificates/cart/{orderId}cart.total.amountMinor é o valor que a emissão vai cobrar. cart.readiness.submittable precisa ser true. cart.versionToken é o token da remoção.
5. Emitir
Seção intitulada “5. Emitir”POST /api/v1/certificates/orders/{orderId}/submit{ "approval": { "confirmed": true, "acknowledgedAmountMinor": 15000 }}acknowledgedAmountMinor tem de ser exatamente cart.total.amountMinor. Outro valor volta outcome: "refused" e refusalReason: "amount_mismatch", sem pedido no provedor.
Um segundo POST com o mesmo pedido volta already_in_progress e não emite de novo.
6. Acompanhar
Seção intitulada “6. Acompanhar”GET /api/v1/certificates/orders?dealId=uuid-da-negociacaoGET /api/v1/certificates/orders/{orderId}A lista traz orderId e status. O detalhe traz status por item: pending, awaiting_webhook, processing, completed, failed. Documento pronto volta como id de entidade, não como URL de download. O PDF continua na interface e na área do cliente.
Correção paga de um item com falha:
POST /api/v1/certificates/orders/{orderId}/items/{itemId}/retryO corpo repete orderId, itemId, fieldPatches e o mesmo approval da emissão. É a ferramenta certificate.retry_item.
Webhooks
Seção intitulada “Webhooks”O Garagem avisa a URL do tenant com o mesmo recorte desta página. Assine estes nomes, ou use todos os eventos:
| Evento | Quando | Corpo em data |
|---|---|---|
payment.updated | O status da cobrança muda | payment, o DTO de GET /payments/{id}. Fatura de aluguel é outro registro e não entra neste evento |
payment.distribution_updated | O status de um repasse muda | distributionId, paymentId, installmentNumber, status. Sem CPF, banco ou PIX |
certificate.order.updated | O pedido ou um item muda de status | orderId, status, rollup, items do GET do pedido |
diligence.updated e diligenceResult.* continuam sendo a linha interna da diligência. Não use esses corpos.
O bloco “Webhooks de Pagamento” em 08 - Webhooks e Eventos é o que o provedor manda para o Garagem. Os três eventos acima saem do Garagem para a sua URL.
Não há evento com o PDF nem com banco/PIX. Se o POST não chegar, leia GET /api/v1/payments/{id} ou GET /api/v1/certificates/orders/{orderId}.