{"openapi":"3.1.0","info":{"title":"API marx","version":"2026-10","summary":"Pagamentos Pix para empresas.","description":"API de pagamentos Pix da marx: cobranças, devoluções, links de pagamento, repasses, Pix Automático, MED e\nnotas fiscais de serviço (NFS-e, beta).\n\n- Guias, exemplos e boas práticas: [/docs](/docs)\n- Autenticação: cabeçalhos `X-Client-Id` e `X-Client-Secret` em todas as chamadas (exceto a página de pagamento).\n- Valores monetários são texto com ponto decimal (`\"19.90\"`). Datas em ISO 8601.\n- Podemos adicionar campos às respostas a qualquer momento: ignore campos desconhecidos.\n"},"servers":[{"url":"https://marx.loco.ltd","description":"Este ambiente"}],"security":[{"ClientId":[],"ClientSecret":[]}],"tags":[{"name":"Cobranças","description":"Cobranças Pix com QR Code e copia e cola. Guia em [/docs/cobrancas](/docs/cobrancas)."},{"name":"Devoluções","description":"Devolução total ou parcial de cobranças pagas. Guia em [/docs/devolucoes](/docs/devolucoes)."},{"name":"Links de pagamento","description":"Página de pagamento pronta. Guia em [/docs/links-de-pagamento](/docs/links-de-pagamento)."},{"name":"Página de pagamento","description":"Endpoints públicos usados pela página `/pay/{token}` (sem credenciais)."},{"name":"Repasses","description":"Envio de Pix para chaves de terceiros. **Liberado por contrato** (sem liberação → `403`)."},{"name":"Pix Automático — clientes","description":"Pagadores das assinaturas. **Liberado por contrato.**"},{"name":"Pix Automático — assinaturas","description":"Recorrência autorizada pelo pagador. Aceita `Idempotency-Key` em POST/PATCH."},{"name":"Pix Automático — cobranças","description":"Cobranças de cada ciclo da assinatura."},{"name":"MED","description":"Infrações do Mecanismo Especial de Devolução. **Liberado por contrato.**"},{"name":"NFS-e — emissores","description":"**Beta, liberado por contrato** (sem liberação → `403`). Emissor (CNPJ prestador), certificado A1 e serviços.\nGuia em [/docs/nfse](/docs/nfse).\n"},{"name":"NFS-e — notas","description":"**Beta, liberado por contrato.** Emissão assíncrona (`202`), consulta, PDF/XML, cancelamento e substituição de\nNFS-e no Padrão Nacional. Guia em [/docs/nfse](/docs/nfse).\n"}],"x-tagGroups":[{"name":"Receber","tags":["Cobranças","Devoluções","Links de pagamento","Página de pagamento"]},{"name":"Enviar","tags":["Repasses"]},{"name":"Recorrência","tags":["Pix Automático — clientes","Pix Automático — assinaturas","Pix Automático — cobranças"]},{"name":"Disputas","tags":["MED"]},{"name":"Notas fiscais (beta)","tags":["NFS-e — emissores","NFS-e — notas"]}],"paths":{"/api/charges":{"post":{"tags":["Cobranças"],"operationId":"createCharge","summary":"Criar cobrança","description":"Gera um Pix com valor definido. A resposta traz o copia e cola (`pix_qrcode`) e um `payment_url` pronto.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["charge"],"properties":{"charge":{"$ref":"#/components/schemas/ChargeInput"}}},"example":{"charge":{"amount":"149.90","reference":"pedido-1001","pix_info1_name":"Pedido","pix_info1_value":"#1001","metadata":{"customer_id":"c_871"}}}}}},"responses":{"201":{"description":"Cobrança criada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Refused"},"422":{"description":"Dados inválidos ou falha ao gerar o Pix. Nenhuma cobrança fica criada; é seguro tentar de novo.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/charges/{txid}":{"get":{"tags":["Cobranças"],"operationId":"getCharge","summary":"Consultar cobrança","parameters":[{"$ref":"#/components/parameters/Txid"}],"responses":{"200":{"description":"Cobrança.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/charges/{txid}/chargeback":{"post":{"tags":["Devoluções"],"operationId":"refundCharge","summary":"Devolver cobrança (total ou parcial)","description":"Solicita a devolução de parte ou de todo o valor de uma cobrança paga. Várias devoluções parciais são permitidas\naté o valor pago. Repetir o mesmo `cancelid` devolve a devolução existente.\n","parameters":[{"$ref":"#/components/parameters/Txid"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["chargeback"],"properties":{"chargeback":{"type":"object","required":["cancelid","amount"],"properties":{"cancelid":{"type":"string","pattern":"^[A-Za-z0-9]{1,35}$","description":"Seu identificador da devolução, único por cobrança."},"amount":{"$ref":"#/components/schemas/Money"}}}}},"example":{"chargeback":{"cancelid":"DEV1001A","amount":"50.00"}}}}},"responses":{"200":{"description":"Devolução aceita. A cobrança volta com a devolução em `refunds`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Charge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"description":"Cobrança não encontrada ou não paga, valor acima do disponível, `cancelid` inválido ou recusa da rede Pix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bills":{"post":{"tags":["Links de pagamento"],"operationId":"createBill","summary":"Criar link de pagamento","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["bill"],"properties":{"bill":{"type":"object","required":["amount"],"properties":{"amount":{"$ref":"#/components/schemas/Money"},"reference":{"type":"string"},"payment_method":{"type":"string","enum":["pix"],"description":"Envie `pix` para gerar o Pix já na criação; omita para o cliente escolher na página."},"metadata":{"$ref":"#/components/schemas/Metadata"}}}}},"example":{"bill":{"amount":"89.00","reference":"fatura-2026-10"}}}}},"responses":{"201":{"description":"Link criado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"422":{"$ref":"#/components/responses/Invalid"}}}},"/api/bills/{id}":{"get":{"tags":["Links de pagamento"],"operationId":"getBill","summary":"Consultar link de pagamento","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Bill"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/pay/{token}":{"get":{"tags":["Página de pagamento"],"operationId":"getPaymentPage","summary":"Dados da página de pagamento","description":"Público (sem credenciais). Usado pela página `/pay/{token}`. Limite de 60 requisições por minuto por IP.","security":[],"parameters":[{"$ref":"#/components/parameters/PaymentToken"}],"responses":{"200":{"description":"Dados mínimos para o pagador.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPage"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/pay/{token}/select_method":{"post":{"tags":["Página de pagamento"],"operationId":"selectPaymentMethod","summary":"Escolher forma de pagamento","description":"Público. Para links sem forma definida, gera o Pix (uma única vez). Cartão ainda não está disponível.","security":[],"parameters":[{"$ref":"#/components/parameters/PaymentToken"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payment_method"],"properties":{"payment_method":{"type":"string","enum":["pix"]}}}}}},"responses":{"200":{"description":"Página atualizada, com o Pix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentPage"}}}},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"429":{"$ref":"#/components/responses/TooManyRequests"}}}},"/api/payouts":{"post":{"tags":["Repasses"],"operationId":"createPayout","summary":"Enviar Pix (repasse)","description":"Requer repasses liberados para a empresa. **Sempre envie `reference`**: repetir o mesmo `reference`\ndevolve o repasse existente (`200`) sem enviar dinheiro de novo.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["payout"],"properties":{"payout":{"$ref":"#/components/schemas/PayoutInput"}}},"example":{"payout":{"amount_payout":"250.00","pix_key":"financeiro@parceiro.com.br","pix_key_type":"EMAIL","pix_info":"Comissão outubro","reference":"comissao-2026-10-parceiro-12"}}}}},"responses":{"201":{"description":"Repasse criado e enviado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"200":{"description":"Já existia um repasse com esse `reference`; nenhum novo envio.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Repasses não liberados para a empresa, ou Pix recusado pela instituição (chave inexistente, limite). O corpo descreve o motivo.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"$ref":"#/components/responses/Invalid"}}}},"/api/payouts/{id}":{"get":{"tags":["Repasses"],"operationId":"getPayout","summary":"Consultar repasse","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Repasse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payout"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Repasse não encontrado."}}}},"/api/med_infractions":{"get":{"tags":["MED"],"operationId":"listMedInfractions","summary":"Listar infrações","description":"As 100 infrações mais recentes da empresa.","responses":{"200":{"description":"Infrações.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MedInfraction"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"}}}},"/api/med_infractions/{id}":{"get":{"tags":["MED"],"operationId":"getMedInfraction","summary":"Consultar infração","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Infração.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MedInfraction"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/med_infractions/{id}/defense":{"post":{"tags":["MED"],"operationId":"defendMedInfraction","summary":"Enviar defesa","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["defesa"],"properties":{"defesa":{"type":"string","description":"Texto da defesa com evidências objetivas."}}}}}},"responses":{"200":{"description":"Defesa enviada; a infração passa para `EM_DEFESA`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MedInfraction"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"}}}},"/api/pix_automatico/customers":{"get":{"tags":["Pix Automático — clientes"],"operationId":"listPaCustomers","summary":"Listar clientes","parameters":[{"name":"document","in":"query","schema":{"type":"string"},"description":"CPF/CNPJ (só dígitos são considerados)."},{"name":"external_id","in":"query","schema":{"type":"string"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Página de clientes.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaCustomer"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"}}},"post":{"tags":["Pix Automático — clientes"],"operationId":"createPaCustomer","summary":"Criar cliente","description":"Se já existir cliente com o mesmo documento, ele é atualizado e devolvido com `200`.","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer"],"properties":{"customer":{"$ref":"#/components/schemas/PaCustomerInput"}}}}}},"responses":{"201":{"description":"Criado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCustomer"}}}},"200":{"description":"Já existia (mesmo documento).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCustomer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"409":{"$ref":"#/components/responses/IdempotencyInFlight"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/api/pix_automatico/customers/{id}":{"get":{"tags":["Pix Automático — clientes"],"operationId":"getPaCustomer","summary":"Consultar cliente","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Cliente.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCustomer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Pix Automático — clientes"],"operationId":"updatePaCustomer","summary":"Atualizar cliente","description":"O documento não pode ser alterado. `PUT` também é aceito (sem suporte a `Idempotency-Key`).","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["customer"],"properties":{"customer":{"$ref":"#/components/schemas/PaCustomerInput"}}}}}},"responses":{"200":{"description":"Atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCustomer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/api/pix_automatico/subscriptions":{"get":{"tags":["Pix Automático — assinaturas"],"operationId":"listPaSubscriptions","summary":"Listar assinaturas","parameters":[{"name":"reference","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["CRIADA","APROVADA","REJEITADA","EXPIRADA","CANCELADA"]}},{"name":"customer_id","in":"query","schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Página de assinaturas.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaSubscription"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"}}},"post":{"tags":["Pix Automático — assinaturas"],"operationId":"createPaSubscription","summary":"Criar assinatura","description":"Repetir o mesmo `reference` devolve a assinatura existente (`200`).","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["subscription"],"properties":{"subscription":{"$ref":"#/components/schemas/PaSubscriptionInput"}}},"example":{"subscription":{"reference":"assinatura-c_871-pro","customer_id":"0b8f6c1e-2d4a-4b7f-9e13-5a6c7d8e9f01","journey":"qrcode","object":"Plano Pro mensal","periodicity":"MENSAL","start_date":"2026-11-05","amount":"59.90","retry_policy":"PERMITE_3R_7D"}}}}},"responses":{"201":{"description":"Criada; aguardando autorização do pagador.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaSubscription"}}}},"200":{"description":"Já existia com esse `reference`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaSubscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"409":{"$ref":"#/components/responses/IdempotencyInFlight"},"422":{"$ref":"#/components/responses/ValidationFailed"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/subscriptions/{id}":{"get":{"tags":["Pix Automático — assinaturas"],"operationId":"getPaSubscription","summary":"Consultar assinatura","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Assinatura.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaSubscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/pix_automatico/subscriptions/{id}/cancel":{"post":{"tags":["Pix Automático — assinaturas"],"operationId":"cancelPaSubscription","summary":"Cancelar assinatura","description":"Cancela a recorrência e as cobranças futuras ainda não enviadas.","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Cancelada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaSubscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/subscriptions/{id}/sync":{"post":{"tags":["Pix Automático — assinaturas"],"operationId":"syncPaSubscription","summary":"Atualizar status agora","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Assinatura atualizada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaSubscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/subscriptions/{id}/request_authorization":{"post":{"tags":["Pix Automático — assinaturas"],"operationId":"requestPaAuthorization","summary":"Pedir autorização no app do pagador (jornada push)","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["destinatario"],"properties":{"destinatario":{"$ref":"#/components/schemas/PaRecipient"}}}}}},"responses":{"200":{"description":"Pedido enviado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaSubscription"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/subscriptions/{subscription_id}/charges":{"parameters":[{"name":"subscription_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"get":{"tags":["Pix Automático — cobranças"],"operationId":"listPaCharges","summary":"Listar cobranças da assinatura","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Página de cobranças.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaCharge"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["Pix Automático — cobranças"],"operationId":"createPaCharge","summary":"Criar cobrança do ciclo","description":"A assinatura precisa estar `APROVADA`. `due_date` dentro do período e pelo menos 2 dias à frente.\nCom valor fixo, `amount` deve ser igual a ele; com mínimo, maior ou igual. Já existindo cobrança para a data, ela é devolvida (`200`).\n","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["charge"],"properties":{"charge":{"type":"object","required":["due_date"],"properties":{"due_date":{"type":"string","format":"date"},"amount":{"$ref":"#/components/schemas/Money"},"reference":{"type":"string"},"info_adicional":{"type":"string","maxLength":140},"metadata":{"$ref":"#/components/schemas/Metadata"}}}}}}}},"responses":{"201":{"description":"Criada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCharge"}}}},"200":{"description":"Já existia para a data.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCharge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"409":{"$ref":"#/components/responses/IdempotencyInFlight"},"422":{"$ref":"#/components/responses/ValidationFailed"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/charges/{id}":{"get":{"tags":["Pix Automático — cobranças"],"operationId":"getPaCharge","summary":"Consultar cobrança do ciclo","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Cobrança.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCharge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/pix_automatico/charges/{id}/cancel":{"post":{"tags":["Pix Automático — cobranças"],"operationId":"cancelPaCharge","summary":"Cancelar cobrança do ciclo","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Cancelada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCharge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/charges/{id}/retry":{"post":{"tags":["Pix Automático — cobranças"],"operationId":"retryPaCharge","summary":"Nova tentativa após falha","description":"Só para assinaturas com `retry_policy` `PERMITE_3R_7D`.","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["date"],"properties":{"date":{"type":"string","format":"date"}}}}}},"responses":{"200":{"description":"Nova tentativa agendada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCharge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/charges/{id}/refund":{"post":{"tags":["Pix Automático — cobranças"],"operationId":"refundPaCharge","summary":"Devolver cobrança do ciclo","description":"Só para cobranças `CONCLUIDA`. Sem `amount`, devolve o valor total.","parameters":[{"$ref":"#/components/parameters/Id"},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"refund":{"type":"object","properties":{"amount":{"$ref":"#/components/schemas/Money"},"refund_id":{"type":"string","pattern":"^[A-Za-z0-9]{1,35}$"}}}}}}}},"responses":{"200":{"description":"Devolução solicitada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCharge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/pix_automatico/charges/{id}/sync":{"post":{"tags":["Pix Automático — cobranças"],"operationId":"syncPaCharge","summary":"Atualizar status agora","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Cobrança atualizada.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaCharge"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"502":{"$ref":"#/components/responses/Upstream"}}}},"/api/nfse/issuers":{"get":{"tags":["NFS-e — emissores"],"operationId":"listNfseIssuers","summary":"Listar emissores","parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Emissores da empresa.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NfseIssuer"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"}}},"post":{"tags":["NFS-e — emissores"],"operationId":"createNfseIssuer","summary":"Cadastrar emissor","description":"O emissor nasce inativo e em teste. Depois envie o certificado, cadastre um serviço e ative (`PATCH` com `active` true).","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseIssuerInput"},"example":{"cnpj":"11.222.333/0001-81","legal_name":"Minha Empresa LTDA","municipal_registration":"0101010101","city_ibge":"4106902","tax_regime":"simples","simples_collection":"das","series":"900","approximate_tax_percent":"6.00"}}}},"responses":{"201":{"description":"Emissor criado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseIssuer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/api/nfse/issuers/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"`id` do emissor ou o CNPJ (só números/letras).","schema":{"type":"string"}}],"get":{"tags":["NFS-e — emissores"],"operationId":"getNfseIssuer","summary":"Consultar emissor","responses":{"200":{"description":"Emissor (com `ready` e `missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseIssuer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["NFS-e — emissores"],"operationId":"updateNfseIssuer","summary":"Alterar ou ativar emissor","description":"Qualquer campo exceto `cnpj`. `active true` só é aceito quando não falta nada (`missing` vazio). A mudança para produção é feita pelo time marx.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseIssuerInput"},"example":{"active":true}}}},"responses":{"200":{"description":"Emissor atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseIssuer"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Dados inválidos, ou emissor ainda não pode ser ativado (`missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseNotReady"}}}}}}},"/api/nfse/issuers/{issuer_id}/certificate":{"parameters":[{"name":"issuer_id","in":"path","required":true,"description":"`id` do emissor ou o CNPJ.","schema":{"type":"string"}}],"get":{"tags":["NFS-e — emissores"],"operationId":"getNfseCertificate","summary":"Dados do certificado A1","description":"Só dados públicos. O arquivo e a senha nunca são devolvidos.","responses":{"200":{"description":"Certificado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseCertificate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Emissor não encontrado ou sem certificado."}}},"put":{"tags":["NFS-e — emissores"],"operationId":"uploadNfseCertificate","summary":"Enviar ou substituir o certificado A1","description":"e-CNPJ A1 (ICP-Brasil) do próprio CNPJ do emissor. Aceito só se abrir com a senha, tiver a chave privada e estiver\nna validade. Guardado criptografado; substitui o anterior na hora.\n","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file","password"],"properties":{"file":{"type":"string","format":"binary","description":"Arquivo .pfx ou .p12."},"password":{"type":"string","format":"password"}}}},"application/json":{"schema":{"type":"object","required":["pfx_base64","password"],"properties":{"pfx_base64":{"type":"string","description":"Arquivo .pfx em Base64."},"password":{"type":"string","format":"password"}}}}}},"responses":{"200":{"description":"Certificado aceito.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseCertificate"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"description":"Senha incorreta, arquivo inválido, certificado vencido ou de outro CNPJ.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}}}},"delete":{"tags":["NFS-e — emissores"],"operationId":"deleteNfseCertificate","summary":"Remover o certificado","description":"O emissor para de emitir até receber outro certificado.","responses":{"204":{"description":"Removido."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/nfse/issuers/{issuer_id}/services":{"parameters":[{"name":"issuer_id","in":"path","required":true,"description":"`id` do emissor ou o CNPJ.","schema":{"type":"string"}}],"get":{"tags":["NFS-e — emissores"],"operationId":"listNfseServices","summary":"Listar serviços do emissor","responses":{"200":{"description":"Serviços.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NfseService"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}},"post":{"tags":["NFS-e — emissores"],"operationId":"createNfseService","summary":"Cadastrar serviço","description":"O primeiro serviço do emissor vira o padrão.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseServiceInput"},"example":{"code":"01.03.01","nbs":"1.1506.21.00","description":"Assinatura de software (SaaS)"}}}},"responses":{"201":{"description":"Serviço criado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseService"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"}}}},"/api/nfse/issuers/{issuer_id}/services/{id}":{"parameters":[{"name":"issuer_id","in":"path","required":true,"schema":{"type":"string"}},{"$ref":"#/components/parameters/Id"}],"patch":{"tags":["NFS-e — emissores"],"operationId":"updateNfseService","summary":"Alterar serviço","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseServiceInput"}}}},"responses":{"200":{"description":"Serviço atualizado.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseService"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/ValidationFailed"}}},"delete":{"tags":["NFS-e — emissores"],"operationId":"deleteNfseService","summary":"Remover serviço","description":"Só serviços ainda não usados em nenhuma nota.","responses":{"204":{"description":"Removido."},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"}}}},"/api/nfse":{"get":{"tags":["NFS-e — notas"],"operationId":"listNfse","summary":"Listar notas","parameters":[{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/NfseStatus"}},{"name":"issuer_id","in":"query","description":"`id` ou CNPJ do emissor.","schema":{"type":"string"}},{"name":"reference","in":"query","schema":{"type":"string"}},{"name":"payment_id","in":"query","schema":{"type":"string"}},{"name":"competence_from","in":"query","schema":{"type":"string","format":"date"}},{"name":"competence_to","in":"query","schema":{"type":"string","format":"date"}},{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/PerPage"}],"responses":{"200":{"description":"Notas, da mais recente para a mais antiga.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Nfse"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"}}},"post":{"tags":["NFS-e — notas"],"operationId":"createNfse","summary":"Emitir nota","description":"Assíncrono: responde `202` e o resultado chega por webhook (`event_type_nfse_authorized` / `event_type_nfse_rejected`).\n`reference` é único por empresa para sempre: repetir devolve a nota existente (`200`), nunca emite outra.\n","parameters":[{"name":"Idempotency-Key","in":"header","description":"Usado como `reference` quando o corpo não traz um.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseInput"},"example":{"reference":"fatura-2026-10-0042","amount":"149.90","competence_date":"2026-10-01","customer":{"tax_id":"11.222.333/0001-81","name":"Cliente LTDA","email":"financeiro@cliente.com.br"},"service":{"code":"010301","description":"Assinatura Pro — outubro/2026"}}}}},"responses":{"202":{"description":"Nota na fila de emissão.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nfse"}}}},"200":{"description":"Já existia uma nota com esse `reference`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nfse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/FeatureDisabled"},"404":{"description":"`issuer_id` não encontrado."},"422":{"description":"Dados inválidos ou emissor não pronto (`missing`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseNotReady"}}}}}}},"/api/nfse/{id}":{"get":{"tags":["NFS-e — notas"],"operationId":"getNfse","summary":"Consultar nota","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"Nota.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nfse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/nfse/{id}/pdf":{"get":{"tags":["NFS-e — notas"],"operationId":"getNfsePdf","summary":"PDF (DANFSe)","description":"Disponível depois da autorização. Notas canceladas ou substituídas saem com marca d'água.","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Nota não encontrada ou ainda não autorizada."}}}},"/api/nfse/{id}/xml":{"get":{"tags":["NFS-e — notas"],"operationId":"getNfseXml","summary":"XML oficial","parameters":[{"$ref":"#/components/parameters/Id"}],"responses":{"200":{"description":"XML da NFS-e autorizada.","content":{"application/xml":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Nota não encontrada ou ainda não autorizada."}}}},"/api/nfse/{id}/cancel":{"post":{"tags":["NFS-e — notas"],"operationId":"cancelNfse","summary":"Cancelar nota","description":"Só notas `authorized`. Responde `202` com `cancellation.status = pending`; ao registrar, chega `event_type_nfse_cancelled`.","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","enum":["error","service_not_provided","other"],"default":"other"},"description":{"type":"string","minLength":15,"maxLength":255,"description":"Opcional; sem ela, um texto padrão do motivo."}}},"example":{"reason":"service_not_provided"}}}},"responses":{"202":{"description":"Cancelamento pedido.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nfse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"}}}},"/api/nfse/{id}/replace":{"post":{"tags":["NFS-e — notas"],"operationId":"replaceNfse","summary":"Substituir nota","description":"Cria uma nota nova que substitui a original (só `authorized`). Envie um `reference` novo e só os campos que mudam.\nQuando a nova for autorizada, a original fica `replaced`. **ME/EPP:** valor, competência e CPF/CNPJ do tomador não\npodem mudar (regra nacional E0063): a API responde `422` com `locked`; cancele e emita outra nota.\n","parameters":[{"$ref":"#/components/parameters/Id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NfseReplaceInput"},"example":{"reference":"fatura-2026-10-0042-v2","service":{"description":"Assinatura Pro — outubro/2026 (contrato 123)"}}}}},"responses":{"202":{"description":"Nota substituta na fila.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Nfse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/Invalid"}}}}},"webhooks":{"evento":{"post":{"operationId":"receiveWebhook","summary":"Notificação enviada para a sua URL","description":"A marx faz um `POST` para a URL cadastrada no painel a cada evento. Responda `2xx` em até 5 segundos.\nFalhas são repetidas após 30 s, 2 min, 10 min, 30 min e 2 h. Use `X-Marx-Event-Id` para descartar duplicados.\nValide `X-Marx-Signature` (HMAC-SHA256 de `\"\u003ctimestamp\u003e.\u003ccorpo\u003e\"`): veja [/docs/assinatura-de-webhooks](/docs/assinatura-de-webhooks).\n","parameters":[{"name":"X-Webhook-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-Marx-Event-Id","in":"header","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"X-Reference","in":"header","schema":{"type":"string"}},{"name":"X-Marx-Timestamp","in":"header","schema":{"type":"string"},"description":"Com assinatura ativada."},{"name":"X-Marx-Signature","in":"header","schema":{"type":"string","example":"t=1759769002,v1=5f2b…"},"description":"Com assinatura ativada."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEnvelope"}}}},"responses":{"2XX":{"description":"Recebido. Qualquer outro status conta como falha."}}}}},"components":{"securitySchemes":{"ClientId":{"type":"apiKey","in":"header","name":"X-Client-Id","description":"Identificador público da integração (painel → Integração)."},"ClientSecret":{"type":"apiKey","in":"header","name":"X-Client-Secret","description":"Chave secreta, exibida uma única vez ao ser gerada."}},"parameters":{"Txid":{"name":"txid","in":"path","required":true,"description":"`pix_txid` da cobrança (32 caracteres).","schema":{"type":"string","pattern":"^[0-9a-f]{32}$"}},"Id":{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},"PaymentToken":{"name":"token","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{16,64}$"}},"Page":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},"PerPage":{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},"IdempotencyKey":{"name":"Idempotency-Key","in":"header","description":"Opcional. Repete a resposta original para a mesma chave e corpo (cabeçalho `Idempotent-Replayed`). Válida por 7 dias.","schema":{"type":"string","maxLength":255}}},"responses":{"Unauthorized":{"description":"Credenciais ausentes ou inválidas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Company not found"}}}},"FeatureDisabled":{"description":"Funcionalidade não liberada para a empresa.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Refused":{"description":"Recusa da rede de pagamentos ou falha de conexão.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Não encontrado (ou de outra empresa).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Invalid":{"description":"Dados inválidos ou operação não permitida no estado atual.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationFailed":{"description":"Dados inválidos.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"}}}},"IdempotencyInFlight":{"description":"Requisição com a mesma `Idempotency-Key` ainda em processamento.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Limite de requisições atingido. Tente de novo em instantes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Upstream":{"description":"Rede Pix temporariamente indisponível. Tente de novo com espera.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Money":{"type":"string","pattern":"^\\d{1,6}([.,]\\d{1,2})?$","description":"Valor em reais, como texto. Respostas podem omitir zeros à direita (`\"149.9\"`).","examples":["149.90"]},"Metadata":{"description":"Dados livres seus (objeto ou texto). Voltam nas respostas e nos webhooks.","oneOf":[{"type":"object","additionalProperties":true},{"type":"string"}]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Mensagem para logs e suporte (pode mudar)."}}},"ValidationError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}]},"LifecycleStatus":{"type":"string","description":"Status normalizado, igual para todos os recursos. Use este campo nas suas regras.","enum":["pending","settled","reversed","failed","approved","expired","cancelled","removed_by_receiver","removed_by_psp"]},"ChargeInput":{"type":"object","required":["amount"],"properties":{"amount":{"$ref":"#/components/schemas/Money"},"reference":{"type":"string","description":"Seu identificador (não é verificado como único)."},"pix_info1_name":{"type":"string","description":"Rótulo exibido no app do pagador."},"pix_info1_value":{"type":"string","description":"Valor exibido no app do pagador."},"metadata":{"$ref":"#/components/schemas/Metadata"},"request_ip":{"type":"string"},"lat":{"type":"string"},"lng":{"type":"string"}}},"Charge":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"pix_txid":{"type":"string","description":"Identificador do Pix; use para consultar e devolver."},"amount":{"$ref":"#/components/schemas/Money"},"amount_system":{"type":["string","null"],"description":"Taxa da marx (quando o contrato define percentual)."},"amount_to_pay":{"type":["string","null"],"description":"Valor líquido para a empresa (`amount − amount_system`)."},"pix_status":{"type":"string","enum":["ATIVA","CONCLUIDA","REMOVIDA_PELO_USUARIO_RECEBEDOR","REMOVIDA_PELO_PSP","DEVOLVIDO"]},"status":{"type":"string","description":"Igual a `pix_status`."},"lifecycle_status":{"$ref":"#/components/schemas/LifecycleStatus"},"pix_qrcode":{"type":["string","null"],"description":"Código copia e cola (EMV). Gere o QR Code a partir dele."},"pix_location":{"type":["string","null"]},"payment_url":{"type":["string","null"],"format":"uri","description":"Página de pagamento pronta."},"payment_token":{"type":["string","null"]},"pix_endtoend":{"type":["string","null"],"description":"Identificador fim a fim do Pix pago."},"pix_payer_name":{"type":["string","null"]},"pix_payer_document":{"type":["string","null"]},"pix_created_at":{"type":["string","null"],"format":"date-time"},"pix_payed_at":{"type":["string","null"],"format":"date-time"},"reference":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"pix_info1_name":{"type":["string","null"]},"pix_info1_value":{"type":["string","null"]},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"Refund":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"refund_id":{"type":"string","description":"O `cancelid` enviado."},"amount":{"$ref":"#/components/schemas/Money"},"status":{"type":"string","enum":["EM_PROCESSAMENTO","DEVOLVIDO","NAO_REALIZADO"]},"lifecycle_status":{"type":"string","enum":["pending","reversed","failed"]},"end_to_end_id":{"type":["string","null"]},"error_message":{"type":["string","null"]},"confirmed_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"Bill":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount":{"$ref":"#/components/schemas/Money"},"payment_token":{"type":"string"},"payment_url":{"type":"string","format":"uri"},"payment_method":{"type":["string","null"],"enum":["pix","credit_card",null]},"status":{"type":"string","enum":["pending","paid"]},"reference":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"created_at":{"type":"string","format":"date-time"}}},"PaymentPage":{"type":"object","properties":{"kind":{"type":"string","enum":["bill","charge"]},"merchant":{"type":"string","description":"Nome da empresa."},"reference":{"type":["string","null"]},"amount":{"$ref":"#/components/schemas/Money"},"status":{"type":"string","enum":["pending","paid","refunded","expired"]},"payment_method":{"type":["string","null"]},"methods":{"type":"object","properties":{"pix":{"type":"boolean"},"credit_card":{"type":"boolean"}}},"pix":{"type":["object","null"],"description":"Presente quando o Pix está pronto e a cobrança está pendente.","properties":{"code":{"type":"string","description":"Copia e cola."},"txid":{"type":"string"}}},"paid_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"PayoutInput":{"type":"object","required":["amount_payout","pix_key"],"properties":{"amount_payout":{"$ref":"#/components/schemas/Money"},"pix_key":{"type":"string"},"pix_key_type":{"type":"string","enum":["EVP","EMAIL","TELEFONE","CPFCNPJ","NAO_INFORMADO"]},"pix_info":{"type":"string","description":"Mensagem ao recebedor (até 30 caracteres recomendado)."},"reference":{"type":"string","description":"Único por empresa; protege contra envio duplicado."},"metadata":{"type":"object","additionalProperties":true},"request_ip":{"type":"string"},"lat":{"type":"string"},"lng":{"type":"string"}}},"Payout":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"amount_payout":{"$ref":"#/components/schemas/Money"},"pix_key":{"type":"string"},"pix_key_type":{"type":["string","null"]},"pix_info":{"type":["string","null"]},"reference":{"type":["string","null"]},"pix_status":{"type":["string","null"],"enum":["EM_PROCESSAMENTO","REALIZADO","NAO_REALIZADO",null]},"lifecycle_status":{"type":"string","enum":["pending","settled","failed"]},"pix_endtoend":{"type":["string","null"]},"paid_at":{"type":["string","null"],"format":"date-time"},"error_message":{"type":["string","null"]},"metadata":{"type":["object","null"],"additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"MedInfraction":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"external_id":{"type":"string"},"end_to_end_id":{"type":"string","description":"Pix contestado."},"protocol":{"type":["string","null"]},"amount":{"$ref":"#/components/schemas/Money"},"status":{"type":"string","description":"Status bruto. Prefira `lifecycle_status`."},"lifecycle_status":{"type":"string","enum":["pending","reversed","failed","cancelled"]},"situation_type":{"type":["string","null"]},"fraud_type":{"type":["string","null"]},"held":{"type":"boolean","description":"Valor bloqueado enquanto a infração está aberta."},"charge_id":{"type":["string","null"],"format":"uuid"},"defense_text":{"type":["string","null"]}}},"PaCustomerInput":{"type":"object","required":["name","document"],"properties":{"external_id":{"type":"string","description":"Seu identificador, único na empresa."},"name":{"type":"string","maxLength":140},"document":{"type":"string","description":"CPF (11) ou CNPJ (14 dígitos)."},"email":{"type":"string","format":"email"},"cep":{"type":"string"},"cidade":{"type":"string"},"logradouro":{"type":"string"},"uf":{"type":"string","minLength":2,"maxLength":2},"metadata":{"type":"object","additionalProperties":true}}},"PaCustomer":{"allOf":[{"$ref":"#/components/schemas/PaCustomerInput"},{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"document_type":{"type":"string","enum":["cpf","cnpj"]},"created_at":{"type":"string","format":"date-time"}}}]},"PaRecipient":{"type":"object","required":["agencia","conta","ispb_participante"],"properties":{"agencia":{"type":"string"},"conta":{"type":"string"},"ispb_participante":{"type":"string","description":"ISPB do banco do pagador."},"document":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"PaSubscriptionInput":{"type":"object","required":["reference","periodicity","start_date"],"properties":{"reference":{"type":"string","description":"Único na empresa."},"customer_id":{"type":"string","format":"uuid","description":"Ou envie `customer`."},"customer":{"$ref":"#/components/schemas/PaCustomerInput"},"journey":{"type":"string","enum":["qrcode","qrcode_with_payment","push"],"default":"qrcode"},"contract":{"type":"string","maxLength":35},"object":{"type":"string","maxLength":35,"description":"Descrição exibida ao pagador."},"periodicity":{"type":"string","enum":["SEMANAL","MENSAL","TRIMESTRAL","SEMESTRAL","ANUAL"]},"start_date":{"type":"string","format":"date"},"end_date":{"type":"string","format":"date"},"amount":{"$ref":"#/components/schemas/Money"},"min_amount":{"$ref":"#/components/schemas/Money"},"initial_amount":{"$ref":"#/components/schemas/Money"},"retry_policy":{"type":"string","enum":["NAO_PERMITE","PERMITE_3R_7D"],"default":"NAO_PERMITE"},"auto_charge":{"type":"boolean","default":true,"description":"A marx cria as cobranças de cada ciclo automaticamente."},"destinatario":{"$ref":"#/components/schemas/PaRecipient"},"metadata":{"type":"object","additionalProperties":true}}},"PaSubscription":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"reference":{"type":"string"},"journey":{"type":"string"},"status":{"type":["string","null"],"enum":["CRIADA","APROVADA","REJEITADA","EXPIRADA","CANCELADA",null]},"lifecycle_status":{"type":"string","enum":["pending","approved","failed","expired","cancelled"]},"contract":{"type":"string"},"object":{"type":["string","null"]},"periodicity":{"type":"string"},"start_date":{"type":"string","format":"date"},"end_date":{"type":["string","null"],"format":"date"},"next_due_date":{"type":["string","null"],"format":"date"},"amount":{"type":["string","null"]},"min_amount":{"type":["string","null"]},"initial_amount":{"type":["string","null"]},"retry_policy":{"type":"string"},"auto_charge":{"type":"boolean"},"pix_copia_e_cola":{"type":["string","null"],"description":"Código para o pagador autorizar (jornadas com QR Code)."},"customer":{"$ref":"#/components/schemas/PaCustomer"},"initial_charge":{"type":["object","null"]},"metadata":{"type":["object","null"]},"error_message":{"type":["string","null"]},"approved_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"PaCharge":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"subscription_id":{"type":"string","format":"uuid"},"subscription_reference":{"type":"string"},"reference":{"type":["string","null"]},"txid":{"type":"string"},"due_date":{"type":"string","format":"date"},"amount":{"$ref":"#/components/schemas/Money"},"amount_system":{"type":["string","null"]},"amount_to_pay":{"type":["string","null"]},"info_adicional":{"type":["string","null"]},"status":{"type":["string","null"],"enum":["CRIADA","ATIVA","CONCLUIDA","REJEITADA","EXPIRADA","CANCELADA",null]},"lifecycle_status":{"type":"string","enum":["pending","settled","failed","expired","cancelled","reversed"]},"end_to_end_id":{"type":["string","null"]},"attempts":{"type":"integer"},"refunds":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"metadata":{"type":["object","null"]},"error_message":{"type":["string","null"]},"paid_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"NfseStatus":{"type":"string","enum":["queued","processing","authorized","rejected","cancelled","replaced","needs_data"],"description":"`queued` na fila · `processing` enviada · `authorized` emitida · `rejected` recusada · `cancelled` cancelada · `replaced` substituída · `needs_data` aguardando dados do tomador (emissão automática)."},"NfseCustomer":{"type":"object","required":["tax_id","name"],"properties":{"tax_id":{"type":"string","description":"CPF (11) ou CNPJ (14, aceita alfanumérico); no exterior, o identificador fiscal estrangeiro. Pontuação é ignorada."},"name":{"type":"string"},"email":{"type":"string","format":"email"},"country":{"type":"string","minLength":2,"maxLength":2,"default":"BR","description":"ISO 3166-1 alfa-2. Diferente de BR = tomador no exterior."},"address":{"type":"object","properties":{"postal_code":{"type":"string"},"street":{"type":"string"},"number":{"type":"string"},"complement":{"type":"string"},"district":{"type":"string"},"city_ibge":{"type":"string","pattern":"^\\d{7}$"}}}}},"NfseInput":{"type":"object","required":["reference","amount","customer"],"properties":{"reference":{"type":"string","maxLength":255,"description":"Seu identificador; único por empresa para sempre."},"amount":{"$ref":"#/components/schemas/Money"},"customer":{"$ref":"#/components/schemas/NfseCustomer"},"service":{"type":"object","properties":{"code":{"type":"string","description":"Código de tributação nacional de um serviço do emissor. Padrão — o serviço padrão."},"description":{"type":"string","maxLength":2000,"description":"Texto da nota. Padrão — a descrição do serviço."}}},"competence_date":{"type":"string","format":"date","description":"Padrão — hoje."},"issuer_id":{"type":"string","description":"`id` ou CNPJ do emissor. Padrão — o emissor ativo mais antigo."},"payment_id":{"type":"string","description":"`id` de uma cobrança marx."},"approximate_tax_percent":{"type":"string","description":"Percentual aproximado de tributos (Lei 12.741)."},"export":{"$ref":"#/components/schemas/NfseExport"},"iss_withheld":{"type":"boolean","default":false,"description":"O tomador retém o ISS (exige CPF/CNPJ e endereço no Brasil do tomador; não vale para exportação nem MEI)."},"iss_rate":{"type":"string","description":"Alíquota do ISS retido (%, até 5). Padrão — a do serviço ou a do emissor."},"ibs_cbs":{"$ref":"#/components/schemas/NfseIbsCbs"}}},"NfseExport":{"type":"object","description":"Obrigatório quando o tomador é do exterior (`customer.country` ≠ BR).","required":["currency","amount_in_currency"],"properties":{"currency":{"type":"string","description":"`USD`, `EUR`, `GBP` ou o código numérico da moeda no Banco Central (3 dígitos)."},"amount_in_currency":{"type":"string","description":"Valor do serviço na moeda estrangeira."},"mode":{"type":"string","enum":["cross_border","consumption_in_brazil","commercial_presence_abroad","temporary_movement_of_people"],"default":"cross_border"},"relationship":{"type":"string","enum":["none","controlled","controlling","affiliate","head_office","branch","other"],"default":"none"},"provider_support":{"type":"string","default":"01","description":"Mecanismo de apoio ao comércio exterior do prestador (01 = nenhum)."},"customer_support":{"type":"string","default":"01","description":"Mecanismo de apoio ao comércio exterior do tomador (01 = nenhum)."},"temporary_goods":{"type":"string","enum":["no","import_declaration","export_declaration"],"default":"no"},"share_with_mdic":{"type":"boolean","default":false}}},"NfseIbsCbs":{"type":["object","null"],"description":"Grupo IBS/CBS. Opcional para o Simples em 2026, obrigatório a partir de 01/01/2027. Padrão — o do serviço ou o do emissor.","properties":{"cst":{"type":"string","pattern":"^\\d{3}$"},"class_code":{"type":"string","pattern":"^\\d{6}$","description":"cClassTrib"},"operation_indicator":{"type":"string","pattern":"^\\d{6}$","description":"cIndOp (ex. 100301)"}}},"Nfse":{"type":"object","properties":{"object":{"type":"string","const":"nfse"},"id":{"type":"string","format":"uuid"},"status":{"$ref":"#/components/schemas/NfseStatus"},"environment":{"type":"string","enum":["test","production"],"description":"`test` = produção restrita, sem valor fiscal."},"reference":{"type":"string"},"issuer":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"cnpj":{"type":"string"}}},"payment_id":{"type":["string","null"]},"number":{"type":["string","null"],"description":"Número da NFS-e (após a autorização)."},"access_key":{"type":["string","null"],"description":"Chave de acesso (50 caracteres)."},"dps":{"type":"object","properties":{"series":{"type":["string","null"]},"number":{"type":["integer","null"]},"id":{"type":["string","null"]}}},"amount":{"$ref":"#/components/schemas/Money"},"competence_date":{"type":"string","format":"date"},"description":{"type":"string"},"service":{"type":["object","null"],"properties":{"code":{"type":"string"},"nbs":{"type":"string"}}},"customer":{"type":"object","properties":{"tax_id":{"type":"string"},"country":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"}}},"errors":{"type":"array","description":"Códigos e mensagens do Ambiente Nacional (recusa ou alertas).","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"detail":{"type":"string"}}}},"cancellation":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["pending","registered","rejected"]},"reason":{"type":["string","null"],"enum":["error","service_not_provided","other",null]},"description":{"type":"string"},"requested_at":{"type":"string","format":"date-time"}}},"export":{"oneOf":[{"$ref":"#/components/schemas/NfseExport"},{"type":"null"}]},"iss_withheld":{"type":"boolean"},"iss_rate":{"type":["string","null"]},"ibs_cbs":{"$ref":"#/components/schemas/NfseIbsCbs"},"replaces_id":{"type":["string","null"],"format":"uuid"},"replaced_by_id":{"type":["string","null"],"format":"uuid"},"authorized_at":{"type":["string","null"],"format":"date-time"},"cancelled_at":{"type":["string","null"],"format":"date-time"},"created_at":{"type":"string","format":"date-time"},"links":{"type":"object","description":"Caminhos do PDF e do XML após a autorização.","properties":{"pdf":{"type":"string"},"xml":{"type":"string"}}}}},"NfseNotReady":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"missing":{"type":"array","items":{"type":"string","enum":["certificate","certificate_expired","service","approximate_tax_percent","ibs_cbs","activation"]}},"details":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}}}}}]},"NfseReplaceInput":{"type":"object","required":["reference"],"description":"Um `reference` novo e só os campos que mudam; os demais vêm da nota original.","properties":{"reference":{"type":"string","maxLength":255},"amount":{"$ref":"#/components/schemas/Money"},"customer":{"$ref":"#/components/schemas/NfseCustomer"},"service":{"type":"object","properties":{"code":{"type":"string"},"description":{"type":"string","maxLength":2000}}},"competence_date":{"type":"string","format":"date"},"approximate_tax_percent":{"type":"string"},"reason":{"type":"string","enum":["other","rejected_by_customer","simples_exclusion","simples_inclusion","immunity_added","immunity_removed"],"default":"other"},"reason_description":{"type":"string","maxLength":255}}},"NfseIssuerInput":{"type":"object","properties":{"cnpj":{"type":"string","description":"Obrigatório no cadastro; não pode ser alterado."},"legal_name":{"type":"string","description":"Razão social (obrigatório no cadastro)."},"municipal_registration":{"type":"string","description":"Inscrição municipal, como no cadastro do Emissor Nacional."},"send_municipal_registration":{"type":"boolean","default":true},"city_ibge":{"type":"string","pattern":"^\\d{7}$","default":"4106902"},"email":{"type":"string","format":"email"},"tax_regime":{"type":"string","enum":["simples","mei","regular"],"default":"simples"},"simples_collection":{"type":"string","enum":["das","iss_outside_das","all_outside_das"],"default":"das"},"special_regime":{"type":"integer","default":0},"series":{"type":"string","pattern":"^(\\d{1,4}|[0-8]\\d{4})$","description":"Série exclusiva da marx, até 89999."},"auto_issue_on_payment":{"type":"boolean","default":false},"email_customer":{"type":"boolean","default":false},"approximate_tax_percent":{"type":"string","description":"Percentual aproximado de tributos padrão (Lei 12.741), ex. \"6.00\". Obrigatório para ME/EPP do Simples, aqui ou em cada serviço."},"iss_withholding_rate":{"type":"string","description":"Alíquota usada quando o tomador retém o ISS (%, até 5)."},"description_footer":{"type":"string","description":"Texto somado ao fim da descrição de toda nota (ex. a frase do Simples Nacional)."},"ibs_cbs":{"$ref":"#/components/schemas/NfseIbsCbs"},"simples_ibs_cbs_regime":{"type":"integer","enum":[1,2,3],"default":1,"description":"NT 009 (regApIBSCBSSN). Enviado quando o novo leiaute entrar em vigor."},"active":{"type":"boolean","description":"Só pode ser `true` com o emissor pronto."}}},"NfseIssuer":{"type":"object","properties":{"object":{"type":"string","const":"issuer"},"id":{"type":"string","format":"uuid"},"cnpj":{"type":"string"},"legal_name":{"type":"string"},"municipal_registration":{"type":["string","null"]},"send_municipal_registration":{"type":"boolean"},"city_ibge":{"type":"string"},"email":{"type":["string","null"]},"tax_regime":{"type":"string","enum":["simples","mei","regular"]},"simples_collection":{"type":["string","null"],"enum":["das","iss_outside_das","all_outside_das",null]},"special_regime":{"type":"integer"},"series":{"type":"string"},"environment":{"type":"string","enum":["test","production"],"description":"Alterado pelo time marx."},"next_dps_number":{"type":"integer"},"approximate_tax_percent":{"type":["string","null"]},"iss_withholding_rate":{"type":["string","null"]},"description_footer":{"type":["string","null"]},"ibs_cbs":{"$ref":"#/components/schemas/NfseIbsCbs"},"simples_ibs_cbs_regime":{"type":"integer"},"auto_issue_on_payment":{"type":"boolean"},"email_customer":{"type":"boolean"},"active":{"type":"boolean"},"ready":{"type":"boolean","description":"Pode emitir notas."},"missing":{"type":"array","items":{"type":"string","enum":["certificate","certificate_expired","service","approximate_tax_percent","ibs_cbs","activation"]}},"certificate":{"oneOf":[{"$ref":"#/components/schemas/NfseCertificate"},{"type":"null"}]},"created_at":{"type":"string","format":"date-time"}}},"NfseCertificate":{"type":"object","description":"Só dados públicos do certificado. O arquivo e a senha nunca são devolvidos.","properties":{"object":{"type":"string","const":"certificate"},"subject":{"type":"string"},"cnpj":{"type":"string"},"serial":{"type":"string"},"fingerprint_sha256":{"type":"string"},"valid_from":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"expired":{"type":"boolean"},"uploaded_at":{"type":"string","format":"date-time"}}},"NfseServiceInput":{"type":"object","properties":{"code":{"type":"string","description":"Código de tributação nacional (6 dígitos; pontuação ignorada)."},"nbs":{"type":"string","description":"Código NBS (9 dígitos)."},"description":{"type":"string","maxLength":2000},"municipal_code":{"type":"string","description":"Código de tributação municipal (3 dígitos), se o município exigir."},"iss_rate":{"type":"string","description":"Alíquota de ISS em %, só quando o ISS não é recolhido pelo Simples."},"approximate_tax_percent":{"type":"string","description":"Percentual aproximado de tributos deste serviço (anexo do Simples). Vazio = padrão do emissor."},"ibs_cbs":{"$ref":"#/components/schemas/NfseIbsCbs"},"simples_activity_code":{"type":"string","pattern":"^\\d{2}$","description":"NT 009 (cAtvSN). Enviado quando o novo leiaute entrar em vigor."},"default":{"type":"boolean"}}},"NfseService":{"type":"object","properties":{"object":{"type":"string","const":"service"},"id":{"type":"string","format":"uuid"},"code":{"type":"string"},"nbs":{"type":"string"},"municipal_code":{"type":["string","null"]},"description":{"type":"string"},"iss_rate":{"type":["string","null"]},"approximate_tax_percent":{"type":["string","null"]},"ibs_cbs":{"$ref":"#/components/schemas/NfseIbsCbs"},"simples_activity_code":{"type":["string","null"]},"default":{"type":"boolean"}}},"WebhookEnvelope":{"type":"object","description":"Formato v2 (recomendado). Empresas no formato legado (v1) recebem apenas os dados brutos.","properties":{"event":{"type":"string","enum":["event_type_charge","event_type_payout","event_type_med","event_type_pix_automatico_subscription","event_type_pix_automatico_charge","event_type_nfse_authorized","event_type_nfse_rejected","event_type_nfse_cancelled","event_type_nfse_replaced","event_type_nfse_cancellation_rejected","event_type_nfse_needs_data","ping"]},"payload":{"description":"O recurso no formato da marx.","oneOf":[{"$ref":"#/components/schemas/Charge"},{"$ref":"#/components/schemas/Payout"},{"$ref":"#/components/schemas/MedInfraction"},{"$ref":"#/components/schemas/PaSubscription"},{"$ref":"#/components/schemas/PaCharge"},{"$ref":"#/components/schemas/Nfse"}]},"original_payload":{"type":"object","description":"Dados brutos da rede de pagamentos, para auditoria. Formato não garantido.","additionalProperties":true}}}}}}