{ "openapi": "3.1.0", "info": { "title": "ArcSign API", "version": "1.0.0", "summary": "Assinatura eletrônica de documentos pelo ArcSign, de sistema para sistema.", "description": "A API do ArcSign deixa o seu sistema enviar documentos para assinar,\nacompanhar cada assinatura e baixar o documento concluído, com o\ncertificado de conclusão.\n\nQuem chama é o seu servidor, com uma chave de API no cabeçalho\n`Authorization`. A organização vem da chave, e de nada mais: não existe\nparâmetro de organização.\n\nRegras que valem em todo endereço:\n\n- os nomes que o seu programa lê — campos, fases, códigos de erro,\n escopos — estão em inglês e não mudam; as frases (`title`, `detail`,\n `label`) estão em português e podem mudar: decida pelo código, nunca\n pela frase;\n- o campo que o endereço não conhece é RECUSADO (422 `invalid_body`, com\n `errors[].code` `unknown_field`): um erro de digitação num campo\n opcional não passa calado;\n- toda resposta leva `X-Request-Id`; a de uma chave reconhecida leva\n também os `RateLimit-*`;\n- as datas vão e voltam em ISO 8601 (a hora com o fuso, ou `Z`).\n", "termsOfService": "https://arcsphera.com/desenvolvedores/termos", "contact": { "name": "Arcsphera", "url": "https://arcsphera.com/desenvolvedores" } }, "servers": [ { "url": "https://app.arcsphera.com/api/v1", "description": "Produção. A chave de teste (`arcs_test_…`) e a de produção (`arcs_live_…`) usam o mesmo endereço; é a chave que diz o ambiente." } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "x-displayName": "Conta", "description": "Quem é a chave, o que ela pode, e os limites que valem." }, { "name": "Envelopes", "x-displayName": "Envelopes", "description": "Enviar, acompanhar, baixar e cancelar." }, { "name": "Templates", "x-displayName": "Modelos", "description": "Os Modelos publicados no ArcSign, com campos e papéis." }, { "name": "Webhooks", "x-displayName": "Webhooks", "description": "Avisos ao seu sistema quando o envelope muda de fase." } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Quem sou eu", "description": "A organização, a chave, os escopos que valem HOJE, os limites e a cota\ndo período. Chame na subida do seu sistema: confirma a chave, os\nescopos e os limites antes do primeiro envio.\n\nOs escopos que valem são o menor de dois: os marcados na chave e as\npermissões que o dono da chave tem hoje. Os limites são os da sua\norganização — o número que o seu programa compara está em\n`limits[].key` e `rateLimits[].counter`.\n", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "A chave vale.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" }, "example": { "organization": { "id": "6f1c9a52-3e0b-4d7e-9a51-0c2f7d3b8e11", "name": "Exemplo Software Ltda." }, "apiKey": { "id": "0b7e2d94-58c1-4f3a-b6e2-9d4a1c7f5e30", "name": "CRM Exemplo — produção", "prefix": "arcs_live_7Hq2…", "scopes": [ "envelopes:read", "envelopes:send" ] }, "owner": { "name": "Ana Souza", "email": "ana@example.com" }, "rateLimits": [ { "counter": "requests_per_minute", "label": "chamadas por minuto", "windowSeconds": 60, "limit": 120, "used": 3, "resetSeconds": 41 }, { "counter": "requests_per_5_seconds", "label": "chamadas em 5 segundos", "windowSeconds": 5, "limit": 30, "used": 1, "resetSeconds": 2 } ], "limits": [ { "key": "test_envelopes_per_week", "label": "Envelopes de teste por semana", "value": 10 }, { "key": "requests_per_minute", "label": "Chamadas por minuto, por chave", "value": 120 } ], "envelopeQuota": { "periodFrom": "2026-10-01T03:00:00.000Z", "periodTo": "2026-11-01T03:00:00.000Z", "quota": 0, "counted": 0, "countedWhen": "completed", "overage": 0 } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/me/revoke": { "post": { "operationId": "revokeMe", "tags": [ "Account" ], "summary": "Revogar esta chave", "description": "A chave que chama revoga A SI MESMA, na hora — o botão de pânico de\nquem viu a chave num commit, num log ou num print. A chamada seguinte\ncom ela recebe 401, e todos os contatos da sua empresa recebem o\ne-mail «Uma chave foi revogada pela própria chave».\n\nUma chave nunca revoga OUTRA (quem roubasse uma derrubaria as boas),\nnem cria outra: a chave nova se pede pelo e-mail, e chega por um link\nque a mostra uma única vez. Vale também com o contrato suspenso ou\nencerrado — revogar é segurança. O corpo é vazio, ou `{}`. Repetir\ndepois de revogada responde 401: a chave já não vale.\n", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "A chave foi revogada. Daqui em diante, ela recebe 401.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "revoked", "revokedAt", "apiKey" ], "properties": { "revoked": { "type": "boolean", "enum": [ true ] }, "revokedAt": { "type": "string", "format": "date-time" }, "apiKey": { "type": "object", "required": [ "id", "name", "prefix" ], "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string", "example": "arcs_live_7Hq2…" } } } } }, "example": { "revoked": true, "revokedAt": "2026-10-22T17:05:12.000Z", "apiKey": { "id": "0b7e2d94-58c1-4f3a-b6e2-9d4a1c7f5e30", "name": "CRM Exemplo — produção", "prefix": "arcs_live_7Hq2…" } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/envelopes": { "get": { "operationId": "listEnvelopes", "tags": [ "Envelopes" ], "summary": "Listar os envelopes", "description": "Os envelopes da organização da chave, em ordem de `updatedAt`\ncrescente, com cursor. Para saber o que mudou desde a última vez,\npasse `updatedSince` e siga `nextCursor` até ele vir `null`.\n\nPeça com SOBREPOSIÇÃO: `updatedSince` = o maior `updatedAt` que você\njá viu MENOS 5 minutos, e descarte o envelope que você já processou\ncom o mesmo `updatedAt`. O `updatedAt` é a hora em que a mudança foi\ngravada, e uma gravação longa pode aparecer na lista com a hora de um\npouco antes da que você já leu. Todo passo que a API mostra — de cada\ndestinatário também (abriu, assinou, o convite saiu) — muda o\n`updatedAt` do envelope.\n\nA chave de teste lista só os envelopes de teste; a de produção, só os\nde verdade.\n", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/EnvelopeStatus" } }, { "name": "updatedSince", "in": "query", "description": "ISO 8601: a data (2026-10-21) ou a data e a hora com o fuso (2026-10-21T15:04:05Z). Só os envelopes alterados desde então.", "schema": { "type": "string", "format": "date-time" } }, { "name": "externalReference", "in": "query", "description": "Igual, exato. Não é única: o contrato reenviado repete.", "schema": { "type": "string", "maxLength": 200 } }, { "name": "onBehalfOfId", "in": "query", "description": "O id do seu cliente, como você o mandou em onBehalfOf.id.", "schema": { "type": "string", "maxLength": 100 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "description": "O nextCursor da página anterior.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Uma página da lista.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EnvelopeSummary" } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createEnvelope", "tags": [ "Envelopes" ], "summary": "Criar um envelope", "description": "Pelo PDF (`documents`, em base64, com `recipients` e `documentType`) ou\npelo Modelo (`templateId` + `fields` + `templateRoles`) — um dos dois.\n`status: \"draft\"` (o padrão) guarda o rascunho; `\"sent\"` envia na\nmesma chamada. Se o envio for recusado, o rascunho FICA e a resposta 422\ntraz o `envelopeId`: corrija e envie por `POST /envelopes/{id}/send`.\n\nO pedido inteiro vai até 25 MB — uns 18 MB de PDF somados, em base64\n(413 acima disso); cada PDF, até 15 MB.\n\nQuem assina recebe o e-mail e a página SEM MARCAS: os dois nomes em\ntexto — «Imobiliária Sol Ltda. enviou este documento pelo CRM Exemplo» —,\nnem o logo do ArcSign nem o seu. O selo do PDF concluído e o\ncertificado de conclusão continuam dizendo quem os emitiu.\n\n`expectedCpf` não preenche o CPF por ninguém: a pessoa digita o dela, e\na página confere que é o esperado (três erros travam a assinatura).\n\nCom a chave de TESTE, o convite sai de verdade — para você ver o e-mail\nchegar —, mas só para as contas confirmadas da sua organização e para\nos contatos confirmados da ArcSign API (quem abriu o link de uma chave\npelo e-mail). Outro destinatário recusa com 403\n`not_available_in_test`, apontando qual.\n", "security": [ { "bearerAuth": [ "envelopes:send" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewEnvelope" }, "examples": { "reference": { "summary": "O pedido completo, pelo PDF", "value": { "title": "Locação — Rua das Flores, 120, ap. 31", "documentType": "OTHER", "externalReference": "crm:contrato:ck9x2", "onBehalfOf": { "id": "imob_42", "name": "Imobiliária Sol Ltda.", "cnpj": "11.222.333/0001-81" }, "status": "sent", "expiresInDays": 15, "documents": [ { "name": "contrato.pdf", "contentBase64": "JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAxMTAKPj4Kc3RyZWFtCnicHYpBCsJQDAX37xRZF4r5aX7yC+JCaOnCjZALiNTSoouKeH5tGRhmMSvOAaaN94TDMD6/42e+32rntmhhLy0loXhAlOKCtK+JhCkzxQtHbay3ztXFkqv1wqaWhf+dvdl8olgQFbrAFT+/TBi+CmVuZHN0cmVhbQplbmRvYmoKCjYgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL09ialN0bQovTiA0Ci9GaXJzdCAyMAovTGVuZ3RoIDIzMgo+PgpzdHJlYW0KeJxVj91qAjEQhe/zFPMCZRK7siuIoNIfKMWihRZKL+LusKRIUsxs0bfvTLpFvAhkzjkzfMeBhQlUFdxC3UAFk2kN87nB1/M3Ab74nrLBp9Bl+JCIhS18GlynITI4s1iYS3bt2R9Sb/6WwGn4OqGG2kfS7eLjlnIajq0saO4+iaOfRzr8EIfW39R21lSNrZuZ0I0n8X2z/6K2RHW8O/HDjj3TKKj2TF3wq3QSbqsdrQUnT+iXMSbWPqVJZKHRaTq2u0JWIIO7Yc9lVNEZXPlMBfXCKRCxTV2IPeBbiMuYw7+gF38B7fhizAplbmRzdHJlYW0KZW5kb2JqCgo3IDAgb2JqCjw8Ci9TaXplIDgKL1Jvb3QgMiAwIFIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL1hSZWYKL0xlbmd0aCAzOAovVyBbIDEgMiAyIF0KL0luZGV4IFsgMCA4IF0KPj4Kc3RyZWFtCnicFcSxDQAgCACwgomzi/+fw1koHYrutJliymmFQ6hfXh5UAAMWCmVuZHN0cmVhbQplbmRvYmoKCnN0YXJ0eHJlZgo1MzMKJSVFT0Y=" } ], "recipients": [ { "type": "SIGNER", "order": 1, "name": "Ana Souza", "email": "ana@example.com", "expectedCpf": "529.982.247-25" }, { "type": "SIGNER", "order": 1, "name": "Bruno Lima", "email": "bruno@example.com" }, { "type": "SIGNER", "order": 2, "name": "Testemunha 1", "email": "t1@example.com" }, { "type": "CARBON_COPY", "order": 3, "name": "Imobiliária Sol", "email": "contratos@example.com" } ] } }, "quickStart": { "summary": "O primeiro envelope de teste — troque o e-mail pelo da sua conta", "value": { "title": "Meu primeiro envelope", "documentType": "OTHER", "status": "sent", "documents": [ { "name": "contrato-de-teste.pdf", "contentBase64": "JVBERi0xLjcKJYGBgYEKCjUgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL0xlbmd0aCAxMTAKPj4Kc3RyZWFtCnicHYpBCsJQDAX37xRZF4r5aX7yC+JCaOnCjZALiNTSoouKeH5tGRhmMSvOAaaN94TDMD6/42e+32rntmhhLy0loXhAlOKCtK+JhCkzxQtHbay3ztXFkqv1wqaWhf+dvdl8olgQFbrAFT+/TBi+CmVuZHN0cmVhbQplbmRvYmoKCjYgMCBvYmoKPDwKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL09ialN0bQovTiA0Ci9GaXJzdCAyMAovTGVuZ3RoIDIzMgo+PgpzdHJlYW0KeJxVj91qAjEQhe/zFPMCZRK7siuIoNIfKMWihRZKL+LusKRIUsxs0bfvTLpFvAhkzjkzfMeBhQlUFdxC3UAFk2kN87nB1/M3Ab74nrLBp9Bl+JCIhS18GlynITI4s1iYS3bt2R9Sb/6WwGn4OqGG2kfS7eLjlnIajq0saO4+iaOfRzr8EIfW39R21lSNrZuZ0I0n8X2z/6K2RHW8O/HDjj3TKKj2TF3wq3QSbqsdrQUnT+iXMSbWPqVJZKHRaTq2u0JWIIO7Yc9lVNEZXPlMBfXCKRCxTV2IPeBbiMuYw7+gF38B7fhizAplbmRzdHJlYW0KZW5kb2JqCgo3IDAgb2JqCjw8Ci9TaXplIDgKL1Jvb3QgMiAwIFIKL0ZpbHRlciAvRmxhdGVEZWNvZGUKL1R5cGUgL1hSZWYKL0xlbmd0aCAzOAovVyBbIDEgMiAyIF0KL0luZGV4IFsgMCA4IF0KPj4Kc3RyZWFtCnicFcSxDQAgCACwgomzi/+fw1koHYrutJliymmFQ6hfXh5UAAMWCmVuZHN0cmVhbQplbmRvYmoKCnN0YXJ0eHJlZgo1MzMKJSVFT0Y=" } ], "recipients": [ { "name": "Você", "email": "o-email-da-sua-conta@example.com" } ] } } } } } }, "responses": { "201": { "description": "O envelope nasceu (e, com `status sent`, saiu).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/envelopes/{id}": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "get": { "operationId": "getEnvelope", "tags": [ "Envelopes" ], "summary": "Consultar um envelope", "description": "A fase, quando entrou nela, cada destinatário com a fase dele e a hora\nde cada passo. Há um limite de consultas ao MESMO envelope por minuto\n(`limits` → `envelope_reads_per_minute` no `GET /me`): para saber que\nmudou, use o webhook ou a lista com `updatedSince`. Não existe e é de\noutra organização são o mesmo 404. O `HEAD` não gasta a consulta.\n", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "responses": { "200": { "description": "O envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/envelopes/{id}/send": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "post": { "operationId": "sendEnvelope", "tags": [ "Envelopes" ], "summary": "Enviar o rascunho", "description": "Envia o rascunho. Enviar o que já saiu responde o envelope, sem\nreenviar nem recontar — a nova tentativa depois da rede que caiu é\nsegura. O corpo é vazio, ou `{}`. Com a chave de teste, o convite vai\nsó às contas e aos contatos confirmados da sua organização (403\n`not_available_in_test` para outro destinatário).\n", "security": [ { "bearerAuth": [ "envelopes:send" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false }, "example": {} } } }, "responses": { "200": { "description": "O envelope, enviado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/envelopes/{id}/void": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "post": { "operationId": "voidEnvelope", "tags": [ "Envelopes" ], "summary": "Cancelar o envelope", "description": "Cancela o envelope em circulação (`sent` ou `delivered`), com o motivo.\nQuem já recebeu o convite recebe um e-mail com o motivo, dizendo que o\nlink não abre mais — sem marcas, como o convite. Quem ainda não tinha\nrecebido não recebe nada. O concluído não se cancela: assinado não se\ndesfaz (409).\n", "security": [ { "bearerAuth": [ "envelopes:void" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "reason" ], "additionalProperties": false, "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "Vai no e-mail a quem já recebeu o convite, e no `voidReason` do envelope." } } }, "example": { "reason": "O locatário desistiu da locação." } } } }, "responses": { "200": { "description": "O envelope, cancelado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Envelope" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/envelopes/{id}/documents/completed": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "get": { "operationId": "getCompletedDocument", "tags": [ "Envelopes" ], "summary": "Baixar o PDF concluído", "description": "O PDF concluído e selado: os documentos e a folha de assinaturas, com o\nselo PAdES do e-CNPJ ICP-Brasil da AUDITCHAIN LTDA e o carimbo do tempo\nRFC 3161 (o carimbo não é ICP-Brasil). Só existe depois que todos\nassinam e o selo sai (409 antes). Guarde-o junto do certificado: o\ncertificado é a prova de quem assinou. O `HEAD` diz o tamanho e o\nSHA-256 sem baixar, e não conta no limite de downloads.\n", "security": [ { "bearerAuth": [ "envelopes:download" ] } ], "responses": { "200": { "description": "O PDF.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Content-SHA256": { "$ref": "#/components/headers/X-Content-SHA256" }, "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/envelopes/{id}/documents/certificate": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "get": { "operationId": "getCertificate", "tags": [ "Envelopes" ], "summary": "Baixar o certificado de conclusão", "description": "O certificado de conclusão, selado: cada passo, com hora, IP e\nnavegador, o resumo de cada arquivo e o aceite do meio eletrônico. Só\nexiste depois do selo (409 antes). O `HEAD` não conta no limite.\n", "security": [ { "bearerAuth": [ "envelopes:download" ] } ], "responses": { "200": { "description": "O PDF do certificado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Content-SHA256": { "$ref": "#/components/headers/X-Content-SHA256" }, "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/envelopes/{id}/documents/{docId}": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "name": "docId", "in": "path", "required": true, "description": "O id de um item de `documents` do envelope.", "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getOriginalDocument", "tags": [ "Envelopes" ], "summary": "Baixar um documento original", "description": "O documento como foi enviado, pelo id que o envelope lista em `documents`. O `HEAD` não conta no limite.", "security": [ { "bearerAuth": [ "envelopes:download" ] } ], "responses": { "200": { "description": "O PDF original.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "X-Content-SHA256": { "$ref": "#/components/headers/X-Content-SHA256" }, "Content-Disposition": { "$ref": "#/components/headers/Content-Disposition" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/templates": { "get": { "operationId": "listTemplates", "tags": [ "Templates" ], "summary": "Listar os Modelos publicados", "description": "Os Modelos publicados, com a versão em uso, os campos (a `key` de cada\n`{{campo}}` do Word, que vai em `fields`, e o `type` dele — a forma do\nvalor) e os papéis (o `roleName` que vai em `templateRoles`). O modelo\ncom o Selo da organização aparece com `supportedByApi: false`: a API\nainda não põe o selo.\n", "security": [ { "bearerAuth": [ "templates:read" ] } ], "responses": { "200": { "description": "Os modelos.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks": { "get": { "operationId": "listWebhooks", "tags": [ "Webhooks" ], "summary": "Listar os webhooks", "description": "Os webhooks da organização e do ambiente da chave (a de teste vê só os de teste; no máximo `limits` → `webhooks` ao todo), sem o segredo.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "A lista.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "post": { "operationId": "createWebhook", "tags": [ "Webhooks" ], "summary": "Cadastrar um webhook", "description": "O endereço HTTPS (porta 443, endereço público) que recebe os eventos\nmarcados. A resposta traz o `secret` UMA vez: guarde-o cifrado no seu\nservidor — é com ele que você confere o `ArcSign-Signature`. A\nrepetição com a mesma `Idempotency-Key` devolve o webhook com\n`secret: null`: perdeu o segredo, troque-o (`rotate-secret`). Endereço\nde rede interna (localhost, 10.x, 192.168.x, os metadados da nuvem)\né recusado.\n\nO webhook é do ambiente da chave que o cadastra: o da chave de teste\n(`test: true`) recebe só os eventos dos envelopes de teste, e só a\nchave de teste o vê; o da chave de produção, o contrário.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewWebhook" }, "example": { "url": "https://crm.example.com/webhooks/arcsign", "events": [ "envelope.completed", "envelope.declined", "envelope.voided", "envelope.expired", "recipient.signed" ], "description": "CRM Exemplo — produção" } } } }, "responses": { "201": { "description": "Cadastrado. O `secret` só aparece aqui.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Location": { "$ref": "#/components/headers/Location" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Webhook" }, { "type": "object", "required": [ "secret" ], "properties": { "secret": { "type": [ "string", "null" ], "description": "O segredo do HMAC, «whsec_» + 32 bytes em base64. Mostrado uma vez: nulo na repetição com a mesma Idempotency-Key.", "example": "whsec_3qK9…" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{id}": { "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "get": { "operationId": "getWebhook", "tags": [ "Webhooks" ], "summary": "Ler um webhook", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "responses": { "200": { "description": "O webhook.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "patch": { "operationId": "updateWebhook", "tags": [ "Webhooks" ], "summary": "Mudar um webhook", "description": "Mude o endereço, os eventos, a descrição ou o `enabled`. `enabled:\ntrue` RELIGA o webhook que se desligou depois de falhar pelos dias\nseguidos de `limits` → `webhook_retry_days` — os dias de falha\nrecomeçam do zero; o que falhou, você reenvia pelo\n`/deliveries/{deliveryId}/retry`. `enabled: false` pausa.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookUpdate" }, "example": { "enabled": true } } } }, "responses": { "200": { "description": "O webhook, como ficou.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "Webhooks" ], "summary": "Apagar um webhook", "description": "Os eventos deixam de sair para ele na hora, e o que estava na fila não sai mais.", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "responses": { "204": { "description": "Apagado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{id}/rotate-secret": { "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhooks" ], "summary": "Trocar o segredo", "description": "O segredo novo vale já, e aparece só nesta resposta (a repetição com a\nmesma `Idempotency-Key` devolve `secret: null`). Por 24 horas o\nanterior assina JUNTO (dois `v1` no `ArcSign-Signature`): troque no\nseu sistema nesse prazo, sem perder aviso. O corpo é vazio, ou `{}`.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "O segredo novo.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "secret", "previousSecretExpiresAt", "webhook" ], "properties": { "secret": { "type": [ "string", "null" ], "description": "Nulo na repetição com a mesma Idempotency-Key.", "example": "whsec_8vP1…" }, "previousSecretExpiresAt": { "type": "string", "format": "date-time" }, "webhook": { "$ref": "#/components/schemas/Webhook" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{id}/test": { "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "post": { "operationId": "testWebhook", "tags": [ "Webhooks" ], "summary": "Enviar um teste", "description": "Manda um evento `webhook.test` AGORA, só para este endereço, e devolve\na entrega com o que o seu endereço respondeu. Não há nova tentativa.\nVale para o webhook desligado — é como se confere antes de religar. O\ncorpo do teste é o `TestEvent`, e não o de um envelope: o seu\nrecebedor responde 2xx a ele também.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "A entrega do teste, com o resultado.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "delivery" ], "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{id}/deliveries": { "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "get": { "operationId": "listWebhookDeliveries", "tags": [ "Webhooks" ], "summary": "A fila de entrega", "description": "Cada evento que saiu (ou tenta sair) para este webhook, da mais nova\npara a mais velha: a situação, as tentativas, o último status e o\nerro. Cada entrega fica 30 dias. O parâmetro errado é 422, com\n`errors[].pointer` `/query/`.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "name": "status", "in": "query", "schema": { "$ref": "#/components/schemas/DeliveryStatus" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "O `nextCursor` da página anterior." } ], "responses": { "200": { "description": "Uma página da fila.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } }, "nextCursor": { "type": [ "string", "null" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } }, "/webhooks/{id}/deliveries/{deliveryId}/retry": { "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/DeliveryId" } ], "post": { "operationId": "retryWebhookDelivery", "tags": [ "Webhooks" ], "summary": "Reenviar agora", "description": "Uma tentativa AGORA, com o MESMO corpo e o mesmo id de evento — o seu\nsistema descarta o repetido. Vale para a entrega que falhou e para a\nque já foi. No webhook desligado, 409 `webhook_disabled`: religue\nantes — e a nova tentativa com a mesma `Idempotency-Key`, depois de\nreligar, reenvia (o 409 que passa não se guarda). O corpo é vazio, ou\n`{}`.\n", "security": [ { "bearerAuth": [ "webhooks:manage" ] } ], "parameters": [ { "$ref": "#/components/parameters/Idempotency-Key" } ], "responses": { "200": { "description": "A entrega, com o resultado desta tentativa.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "delivery" ], "properties": { "delivery": { "$ref": "#/components/schemas/Delivery" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "423": { "$ref": "#/components/responses/Locked" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" }, "503": { "$ref": "#/components/responses/ServiceUnavailable" } } } } }, "webhooks": { "envelope.sent": { "post": { "summary": "Envelope enviado", "description": "O envelope saiu (Rascunho → Enviado).\n\nO ArcSign chama o seu endereço com este corpo. COMO RECEBER: responda 2xx\nem até 10 s — só 2xx conta, e redirecionamento é falha. Confira o\n`ArcSign-Signature` e recuse o `t` com mais de 5 minutos (a tolerância\ndo Standard Webhooks). O aviso pode chegar mais de uma vez (descarte\npelo `id`) e fora de ordem (compare `data.envelope.statusChangedAt`). A\nfalha volta em 1 min, 5 min, 30 min, 2 h, 6 h e de 24 em 24 h, pelos\ndias de `limits` → `webhook_retry_days`; falhar todos esses dias\nseguidos desliga o webhook, e avisamos quem o cadastrou.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "envelope.sent", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "sent", "statusChangedAt": "2026-10-21T18:04:05.123Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": null } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "envelope.delivered": { "post": { "summary": "Envelope aberto", "description": "A primeira pessoa abriu o envelope, com o código do e-mail conferido (Enviado → Entregue).\n\nCOMO RECEBER: o mesmo do `envelope.sent` — 2xx em até 10 s, a\nassinatura conferida, o `t` de até 5 minutos, o repetido descartado\npelo `id` e o fora de ordem por `data.envelope.statusChangedAt`.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "envelope.delivered", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "delivered", "statusChangedAt": "2026-10-21T18:04:05.123Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": null } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "recipient.signed": { "post": { "summary": "Alguém assinou", "description": "Um Signatário assinou — ou o selo da organização assinou na vez dele (`recipient.type` SEAL). `data.recipient` diz qual destinatário, sem nome nem e-mail.\n\nCOMO RECEBER: o mesmo do `envelope.sent` — 2xx em até 10 s, a\nassinatura conferida, o `t` de até 5 minutos, o repetido descartado\npelo `id` e o fora de ordem por `data.envelope.statusChangedAt`. O\núltimo Signatário manda este E o `envelope.completed`, com a mesma\nhora: ordene os `recipient.*` pelo `timestamp`.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "recipient.signed", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "delivered", "statusChangedAt": "2026-10-21T17:58:41.902Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": { "id": "2d8f4b6a-1c3e-4f5a-9b7d-0e2c4a6f8b13", "type": "SIGNER", "order": 1, "status": "signed" } } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "recipient.declined": { "post": { "summary": "Alguém recusou", "description": "Um Signatário recusou. Chega junto do envelope.declined, que para o envelope para todos.\n\nCOMO RECEBER: o mesmo do `envelope.sent`.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "recipient.declined", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "declined", "statusChangedAt": "2026-10-21T18:04:05.123Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": { "id": "2d8f4b6a-1c3e-4f5a-9b7d-0e2c4a6f8b13", "type": "SIGNER", "order": 1, "status": "declined" } } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "envelope.completed": { "post": { "summary": "Envelope concluído", "description": "O último Signatário assinou. O PDF selado pode levar alguns segundos: se o download responder 409 `document_not_ready`, tente de novo em instantes.\n\nCOMO RECEBER: o mesmo do `envelope.sent`.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "envelope.completed", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "completed", "statusChangedAt": "2026-10-21T18:04:05.123Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": null } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "envelope.declined": { "post": { "summary": "Envelope recusado", "description": "A recusa de alguém parou o envelope para todos.\n\nCOMO RECEBER: o mesmo do `envelope.sent`.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "envelope.declined", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "declined", "statusChangedAt": "2026-10-21T18:04:05.123Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": null } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "envelope.voided": { "post": { "summary": "Envelope cancelado", "description": "Quem enviou cancelou o envelope em circulação, com o motivo (o GET do envelope traz o `voidReason`). Quem já tinha recebido o convite recebe o e-mail do cancelamento.\n\nCOMO RECEBER: o mesmo do `envelope.sent`.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "envelope.voided", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "voided", "statusChangedAt": "2026-10-21T18:04:05.123Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": null } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "envelope.expired": { "post": { "summary": "Envelope expirado", "description": "O prazo para assinar venceu.\n\nCOMO RECEBER: o mesmo do `envelope.sent`.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_4f1c2b9a7e3d5c0a8b6f2e1d", "type": "envelope.expired", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "envelope": { "id": "9b2e6c1d-4a7f-4e3b-8c5d-2f1a0e9b7c64", "status": "expired", "statusChangedAt": "2026-10-21T18:04:05.123Z", "externalReference": "crm:contrato:3f9a1c2e-7b4d-4e8a-9c1f-5d2b6a0e8f73", "onBehalfOf": { "id": "7c3e9a1b-2d4f-4a6b-8e0c-1f5d3b7a9e21" }, "test": false }, "recipient": null } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } }, "webhook.test": { "post": { "summary": "O teste do webhook", "description": "Só o «Enviar um teste» (`POST /webhooks/{id}/test`, ou o botão do painel) manda este: confere o endereço e a assinatura. Não se marca nos `events` do webhook, não tem nova tentativa e não conta para o desligamento. O corpo NÃO traz envelope — o seu recebedor responde 2xx a ele também.\n\nOs cabeçalhos e a assinatura são os mesmos dos outros eventos.\n", "parameters": [ { "$ref": "#/components/parameters/ArcSign-Signature" }, { "$ref": "#/components/parameters/ArcSign-Event-Id" }, { "$ref": "#/components/parameters/ArcSign-Event-Type" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Id" }, { "$ref": "#/components/parameters/ArcSign-Delivery-Attempt" }, { "$ref": "#/components/parameters/webhook-id" }, { "$ref": "#/components/parameters/webhook-timestamp" }, { "$ref": "#/components/parameters/webhook-signature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestEvent" }, "example": { "id": "evt_9a2c4e6b8d0f1a3c5e7b9d1f", "type": "webhook.test", "timestamp": "2026-10-21T18:04:05.123Z", "data": { "webhook": { "id": "3e5a7c9b-1d2f-4a6c-8e0b-2d4f6a8c0e13" } } } } } }, "responses": { "200": { "description": "Recebido. Qualquer 2xx serve; a resposta é lida até 4 KB e descartada." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "arcs_live_… ou arcs_test_…", "description": "A chave vai SÓ no cabeçalho `Authorization: Bearer arcs_live_…`. A\nchave na URL é recusada com 400 (`api_key_in_url`): a URL vai para o\nlog. A chave de teste (`arcs_test_…`) nasce no cadastro; a de\nprodução (`arcs_live_…`), depois que a Arcsphera libera a produção.\n\nOs escopos: `envelopes:read` (consultar), `envelopes:send` (enviar),\n`envelopes:download` (baixar os documentos), `envelopes:void`\n(cancelar), `templates:read` (consultar os modelos) e\n`webhooks:manage` (gerenciar os webhooks). Cada operação diz o seu no\n`security`.\n" } }, "parameters": { "Idempotency-Key": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Obrigatória em TODO POST. Escolhida por você, estável por registro (o\nid do contrato + a versão): de 1 a 255 caracteres ASCII visíveis, sem\nespaço. A mesma chave no mesmo endereço com o mesmo corpo devolve a\nresposta guardada, sem fazer nada de novo, com o cabeçalho\n`Idempotent-Replayed: true` (e o `Location`, no 201); com outro corpo\nou noutro endereço, 422; com o primeiro pedido ainda rodando, 409.\nGuardada por chave de API, pelas horas de `limits` →\n`idempotency_key_hours`. A recusa de validação (o 400, o 422 que aponta\ncampos) e o conflito que passa (`delivery_in_progress`,\n`webhook_disabled`) não se guardam: corrija e mande de novo com a\nmesma chave.\n", "schema": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[\\x21-\\x7E]+$" } }, "ArcSign-Signature": { "name": "ArcSign-Signature", "in": "header", "required": true, "description": "t=,v1=: HMAC-SHA256 de \"{t}.{corpo bruto}\" com o segredo INTEIRO (whsec_…) como chave. Nas 24 h depois de trocar o segredo vêm dois v1: vale se qualquer um conferir. Recuse o t com mais de 5 minutos.", "schema": { "type": "string", "example": "t=1761060245,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" } }, "ArcSign-Event-Id": { "name": "ArcSign-Event-Id", "in": "header", "required": true, "description": "O id do evento, o mesmo do `id` do corpo. Descarte o repetido por ele.", "schema": { "type": "string", "example": "evt_4f1c2b9a7e3d5c0a8b6f2e1d" } }, "ArcSign-Event-Type": { "name": "ArcSign-Event-Type", "in": "header", "required": true, "description": "O tipo do evento, o mesmo do `type` do corpo.", "schema": { "type": "string", "example": "envelope.completed" } }, "ArcSign-Delivery-Id": { "name": "ArcSign-Delivery-Id", "in": "header", "required": true, "description": "A entrega — é o `deliveryId` do reenvio pela API.", "schema": { "type": "string" } }, "ArcSign-Delivery-Attempt": { "name": "ArcSign-Delivery-Attempt", "in": "header", "required": true, "description": "1 na primeira tentativa, 2 na segunda…", "schema": { "type": "integer" } }, "webhook-id": { "name": "webhook-id", "in": "header", "required": true, "description": "Standard Webhooks: o id do evento.", "schema": { "type": "string" } }, "webhook-timestamp": { "name": "webhook-timestamp", "in": "header", "required": true, "description": "Standard Webhooks: o mesmo t, em segundos Unix.", "schema": { "type": "integer" } }, "webhook-signature": { "name": "webhook-signature", "in": "header", "required": true, "description": "Standard Webhooks: v1, — HMAC-SHA256 de \"{id}.{t}.{corpo}\" com os bytes depois de «whsec_» (base64). Quem usa a biblioteca do padrão passa o segredo como está. Use UM dos dois cabeçalhos de assinatura.", "schema": { "type": "string" } }, "EnvelopeId": { "name": "id", "in": "path", "required": true, "description": "O `id` do envelope (nunca o `number`). O de outra organização responde o mesmo 404 do que não existe.", "schema": { "type": "string", "format": "uuid" } }, "WebhookId": { "name": "id", "in": "path", "required": true, "description": "O `id` do webhook. O de outro ambiente ou de outra organização responde o mesmo 404 do que não existe.", "schema": { "type": "string", "format": "uuid" } }, "DeliveryId": { "name": "deliveryId", "in": "path", "required": true, "description": "O `id` da entrega, como a fila a lista (e o cabeçalho `ArcSign-Delivery-Id` o traz).", "schema": { "type": "string", "format": "uuid" } } }, "headers": { "X-Request-Id": { "description": "O identificador do pedido, em TODA resposta. Está na trilha e no log; é o que o suporte pede.", "schema": { "type": "string", "example": "req_8Jm2kQx7VbT1oP3s" } }, "RateLimit-Limit": { "description": "O limite da janela de CHAMADAS da chave que mais aperta (por minuto, ou a rajada de 5 s). Vem em toda resposta de uma chave reconhecida — no sucesso e no erro dela —, e não no 401, no 400 `api_key_in_url`, no 429 `too_many_failed_attempts` nem no 503 `api_unavailable`, que acontecem antes de saber de quem é a chave. No 429 dos envelopes (os de teste da semana, os convites da hora, as consultas ao mesmo envelope, os downloads), ele continua sendo o das chamadas da chave: o corpo do problema (`limit`, `window`, `retryAfter`, `resetsAt`) diz o limite que valeu.\n", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Quantas chamadas ainda cabem nessa janela.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Segundos até a janela virar.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Segundos até poder tentar de novo. Vem no 429, e no 409 que passa sozinho (`idempotency_in_progress`, `delivery_in_progress`).", "schema": { "type": "integer" } }, "WWW-Authenticate": { "description": "No 401: `Bearer realm=\"arcsign\"` — a chave vai no `Authorization: Bearer`.", "schema": { "type": "string" } }, "Location": { "description": "O endereço do que nasceu (`/api/v1/envelopes/{id}`, `/api/v1/webhooks/{id}`) — também na repetição com a mesma Idempotency-Key.", "schema": { "type": "string" } }, "Idempotent-Replayed": { "description": "`true` quando a resposta é a GUARDADA de um pedido anterior com a mesma Idempotency-Key — nada foi feito de novo.", "schema": { "type": "string", "enum": [ "true" ] } }, "X-Content-SHA256": { "description": "O SHA-256 do arquivo, em hexadecimal.", "schema": { "type": "string" } }, "Content-Disposition": { "description": "`attachment`, com o nome em ASCII (`filename`) e o nome de verdade em UTF-8 (`filename*`, RFC 6266).", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Corpo que não é JSON (`malformed_request`), `Idempotency-Key` faltando ou inválida, ou a chave na URL (`api_key_in_url`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Unauthorized": { "description": "Sem chave, chave desconhecida, revogada ou vencida — sempre a mesma resposta, para não dizer qual dos casos é.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "WWW-Authenticate": { "$ref": "#/components/headers/WWW-Authenticate" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Forbidden": { "description": "A chave existe, mas não tem o escopo; ou o dono perdeu a permissão ou foi desativado; ou o IP não está na lista; ou a organização não contratou a ArcSign API; ou a chave de teste pediu o que o teste não faz (`not_available_in_test`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "NotFound": { "description": "Não existe, ou é de outra organização — as duas respostas são iguais.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Conflict": { "description": "A fase não permite (`envelope_not_in_circulation`, `envelope_not_draft`, `document_not_ready`), o webhook já existe ou está desligado, ou o primeiro pedido com esta `Idempotency-Key` ainda está rodando — esse, e a entrega que está saindo, voltam com `Retry-After`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "PayloadTooLarge": { "description": "O pedido passa do tamanho máximo (`payload_too_large`) — 25 MB no envelope, 16 KB no webhook; `limitBytes` diz o número.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "UnprocessableEntity": { "description": "Campos a corrigir (`invalid_body`, e `errors[]` aponta cada um — no corpo, `/campo`; na URL, `/query/`), a `Idempotency-Key` já usada noutro pedido, ou a regra de negócio recusou (o `detail` diz por quê).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Locked": { "description": "A licença está só de leitura (`license_read_only`) — a API lê, e não grava.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "TooManyRequests": { "description": "Um limite foi atingido. `Retry-After` diz quando voltar, e o corpo diz o número que valeu (`limit`, `window`, `retryAfter`; nos envelopes de teste, `resetsAt`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "InternalError": { "description": "O erro que ninguém previu (`internal_error`). Nada de dentro vai no corpo; o `requestId` liga o pedido à linha do nosso log — mande-o ao suporte se repetir.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "ServiceUnavailable": { "description": "O banco está só de leitura (a máquina cópia), o antivírus está fora do ar, a instalação não tem a configuração da API ou a do webhook.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Problem": { "type": "object", "description": "Os erros seguem a RFC 9457 (`application/problem+json`), com dois\ncampos a mais: `code`, estável, em inglês — é o que o seu programa\nlê — e `errors[]`, com o `pointer` do campo. Trate o erro pelo `code`,\nnunca pela frase: a frase pode mudar, o `code` não. Mostre o `detail`\nao seu usuário e guarde o `requestId`. Os campos de limite (`limit`,\n`window`, `retryAfter`, `resetsAt`, `limitBytes`) e o `envelopeId`\nvêm só nos erros que os usam.\n", "required": [ "type", "title", "status", "code", "detail", "requestId" ], "properties": { "type": { "type": "string", "format": "uri", "example": "https://arcsphera.com/docs/api/errors/scope_missing" }, "title": { "type": "string", "example": "A chave não tem este escopo" }, "status": { "type": "integer", "example": 403 }, "code": { "type": "string", "example": "scope_missing", "enum": [ "malformed_request", "idempotency_key_required", "idempotency_key_invalid", "api_key_in_url", "unauthorized", "not_available_in_test", "scope_missing", "owner_lacks_permission", "owner_inactive", "ip_not_allowed", "license_required", "not_found", "idempotency_in_progress", "envelope_not_in_circulation", "envelope_not_draft", "document_not_ready", "idempotency_key_reused", "invalid_body", "document_invalid", "document_infected", "not_supported_by_api", "blocked_by_rule", "envelope_not_sent", "license_read_only", "rate_limited", "too_many_failed_attempts", "test_weekly_limit", "invite_limit", "webhook_limit_reached", "webhook_already_exists", "webhook_disabled", "delivery_in_progress", "webhooks_unavailable", "api_unavailable", "read_only_database", "antivirus_unavailable", "payload_too_large", "internal_error" ] }, "detail": { "type": "string", "example": "Esta chave não tem o escopo envelopes:send. Crie uma chave com ele." }, "instance": { "type": "string", "description": "O caminho do pedido." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" } }, "requestId": { "type": "string", "example": "req_8Jm2kQx7VbT1oP3s" }, "limit": { "type": "integer", "description": "O limite que valeu (no 429)." }, "window": { "type": "integer", "description": "A janela do limite, em segundos (no 429)." }, "retryAfter": { "type": "integer", "description": "Segundos até poder tentar de novo — o mesmo do Retry-After." }, "resetsAt": { "type": "string", "format": "date-time", "description": "Quando o limite semanal dos envelopes de teste volta (`test_weekly_limit`)." }, "limitBytes": { "type": "integer", "description": "O tamanho máximo do pedido (`payload_too_large`)." }, "envelopeId": { "type": "string", "format": "uuid", "description": "O rascunho que FICOU quando o envio foi recusado (`envelope_not_sent`, e o envio do POST /envelopes com status sent) ou o antivírus não respondeu." } } }, "FieldError": { "type": "object", "required": [ "pointer", "code" ], "properties": { "pointer": { "type": "string", "description": "JSON Pointer (RFC 6901) do campo, como /recipients/2/email; o parâmetro da URL vem como /query/.", "example": "/recipients/2/email" }, "code": { "type": "string", "example": "required", "description": "O que há com o campo: `required`, `type`, `enum`, `format`,\n`max_length`, `min_items`, `max_items`, `range`, `date`, `email`,\n`base64`, `invalid_pdf`, `invalid_cpf`, `invalid_cnpj`,\n`duplicate`, `conflict`, `signer_only`, `requires_verify_cnpj`,\n`not_allowed_with_template`, `number_as_text` (o número JSON em\n`fields`: mande texto), `unknown_field` (o campo que o endereço\nnão conhece), `not_supported_by_api` (o SEAL),\n`not_available_in_test`, `unknown_role`, `not_found`,\n`not_published`, `invalid` (o cursor) e `rejected` (a regra do\nproduto recusou; o `detail` diz por quê).\n" } } }, "Me": { "type": "object", "required": [ "organization", "apiKey", "owner", "rateLimits", "limits", "envelopeQuota" ], "properties": { "organization": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": [ "string", "null" ] } } }, "apiKey": { "type": "object", "required": [ "id", "name", "prefix", "scopes" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "prefix": { "type": "string", "description": "O começo visível da chave, para reconhecê-la." }, "scopes": { "type": "array", "description": "Os escopos que VALEM hoje.", "items": { "$ref": "#/components/schemas/Scope" } } } }, "owner": { "type": "object", "description": "O usuário dono da chave. A chave age como ele, e para quando ele perde a permissão.", "required": [ "name", "email" ], "properties": { "name": { "type": [ "string", "null" ], "description": "Nulo quando a conta não tem nome." }, "email": { "type": "string" } } }, "rateLimits": { "type": "array", "description": "Os contadores de chamada, com o que já se usou na janela.", "items": { "type": "object", "required": [ "counter", "label", "windowSeconds", "limit", "used", "resetSeconds" ], "properties": { "counter": { "type": "string", "enum": [ "requests_per_minute", "requests_per_5_seconds" ], "description": "A chave do contador — a mesma do número em `limits`." }, "label": { "type": "string" }, "windowSeconds": { "type": "integer" }, "limit": { "type": "integer" }, "used": { "type": "integer" }, "resetSeconds": { "type": "integer" } } } }, "limits": { "type": "array", "description": "Os números que valem para a organização (o de fábrica, ou o que o negócio fechado mudou).", "items": { "type": "object", "required": [ "key", "label", "value" ], "properties": { "key": { "$ref": "#/components/schemas/LimitKey" }, "label": { "type": "string" }, "value": { "type": "integer" } } } }, "envelopeQuota": { "type": "object", "description": "A cota de envelopes do período.", "required": [ "periodFrom", "periodTo", "quota", "counted", "countedWhen", "overage" ], "properties": { "periodFrom": { "type": "string", "format": "date-time" }, "periodTo": { "type": "string", "format": "date-time" }, "quota": { "type": "integer" }, "counted": { "type": "integer", "description": "Os envelopes que contaram na cota no período — os CONCLUÍDOS (a 1b, 21/10/2026)." }, "countedWhen": { "type": "string", "enum": [ "completed" ], "description": "Quando o envelope conta: ao concluir. O recusado, o expirado e o cancelado não contam." }, "overage": { "type": "integer" } } } } }, "LimitKey": { "type": "string", "description": "A chave de cada número do `/me`: `test_envelopes_per_week` (envelopes\nde teste por semana), `requests_per_minute` e `requests_per_5_seconds`\n(as chamadas da chave), `envelope_reads_per_minute` (consultas ao mesmo\nenvelope), `document_downloads_per_hour` (downloads do mesmo\ndocumento), `invitations_per_hour` (convites da organização),\n`active_api_keys`, `webhooks`, `webhook_retry_days` (os dias de novas\ntentativas, e de falha seguida até desligar) e `idempotency_key_hours`.\n", "enum": [ "test_envelopes_per_week", "requests_per_minute", "requests_per_5_seconds", "envelope_reads_per_minute", "document_downloads_per_hour", "invitations_per_hour", "active_api_keys", "webhooks", "webhook_retry_days", "idempotency_key_hours" ] }, "Scope": { "type": "string", "enum": [ "envelopes:read", "envelopes:send", "envelopes:download", "envelopes:void", "templates:read", "webhooks:manage" ] }, "EnvelopeStatus": { "type": "string", "description": "draft (rascunho), sent (enviado), delivered (alguém abriu), completed (todos assinaram), declined (alguém recusou), voided (cancelado), expired (venceu).", "enum": [ "draft", "sent", "delivered", "completed", "declined", "voided", "expired" ] }, "RecipientStatus": { "type": "string", "description": "created (ainda não é a vez), sent (o convite saiu), delivered (abriu), signed (assinou), declined (recusou).", "enum": [ "created", "sent", "delivered", "signed", "declined" ] }, "RecipientType": { "type": "string", "description": "SIGNER (assina), CARBON_COPY (recebe cópia), SEAL (o selo da organização — a API ainda não o põe).", "enum": [ "SIGNER", "CARBON_COPY", "SEAL" ] }, "DocumentType": { "type": "string", "enum": [ "EMPLOYMENT_CONTRACT", "INTERNSHIP_AGREEMENT", "SERVICES_AGREEMENT", "B2B_AGREEMENT", "SUPPLIER_AGREEMENT", "DATA_PROCESSING_AGREEMENT", "NDA", "CONTRACT_AMENDMENT", "INTERNAL_POLICY", "OTHER" ] }, "TemplateFieldType": { "type": "string", "description": "O tipo de um campo do Modelo, e a forma do valor que vai em `fields`\n(sempre TEXTO; `true`/`false` também no BOOLEAN). O número JSON é\nrecusado (`number_as_text`): `72.125` seria lido como setenta e dois\nmil, na leitura brasileira.\n\n- `TEXT` — qualquer texto de uma linha.\n- `CPF` — os 11 dígitos, com ou sem pontuação.\n- `CNPJ` — os 14 caracteres (numérico ou alfanumérico), com ou sem pontuação.\n- `CURRENCY` — em reais: `5800`, `5.800,00`, `R$ 5.800,00`; o ponto com 1 ou 2 casas no fim é decimal (`5800.50`).\n- `DATE` — `2026-11-03` ou `03/11/2026`.\n- `NUMBER` — como a moeda, sem o `R$`: a vírgula é o decimal (`72,125`); o ponto é milhar, menos com 1 ou 2 casas no fim (`72.5`).\n- `LIST` — uma das `options` do campo, igual.\n- `BOOLEAN` — `true`/`false`, ou «Sim»/«Não».\n", "enum": [ "TEXT", "CPF", "CNPJ", "CURRENCY", "DATE", "NUMBER", "LIST", "BOOLEAN" ] }, "OnBehalfOf": { "type": "object", "description": "O seu cliente, em nome de quem o envelope sai. Quem assina lê os dois\nnomes — o dele e o da sua organização. O nome não é conferido (o\ncertificado diz «informado por» você); o CNPJ e o CPF, só pelos dígitos\nverificadores. No máximo um dos dois. A separação entre os seus\nclientes é sua: o filtro `onBehalfOfId` ajuda, mas não é parede.\n", "required": [ "name" ], "additionalProperties": false, "properties": { "id": { "type": [ "string", "null" ], "maxLength": 100, "description": "O id do cliente no seu sistema." }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "cnpj": { "type": [ "string", "null" ], "description": "Com ou sem pontuação; a resposta devolve só os caracteres." }, "cpf": { "type": [ "string", "null" ], "description": "Com ou sem pontuação; a resposta devolve só os dígitos." } } }, "NewRecipient": { "type": "object", "required": [ "name", "email" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "SIGNER", "CARBON_COPY" ], "default": "SIGNER", "description": "SEAL (o Selo da organização) ainda não sai pela API: vem como errors[].code not_supported_by_api; outro valor, como enum." }, "order": { "type": "integer", "minimum": 1, "maximum": 99, "default": 1, "description": "Mesma ordem = ao mesmo tempo; a próxima só recebe quando a anterior termina." }, "name": { "type": "string", "maxLength": 200 }, "email": { "type": "string", "format": "email" }, "expectedCpf": { "type": "string", "description": "Só no SIGNER. A pessoa digita o CPF dela, e a página confere que é este." }, "verifyCpfAtReceita": { "type": "boolean", "default": false, "description": "Só no SIGNER: confere CPF e nascimento na Receita (pago; não roda com a chave de teste)." }, "verifyCnpjAtReceita": { "type": "boolean", "default": false, "description": "Só no SIGNER: confere na Receita o CNPJ da empresa que a pessoa representa (pago)." }, "verifyCnpjPartners": { "type": "boolean", "default": false, "description": "Com verifyCnpjAtReceita: confere também o nome no quadro de sócios." } } }, "NewTemplateRole": { "type": "object", "required": [ "roleName" ], "additionalProperties": false, "properties": { "roleName": { "type": "string", "description": "O roleName do papel, como GET /templates o lista." }, "name": { "type": "string", "description": "Vazio no SIGNER cujo nome vem de um campo (nameFromField)." }, "email": { "type": "string", "format": "email" }, "expectedCpf": { "type": "string" } } }, "NewEnvelope": { "description": "UM dos dois caminhos: pelo PDF (`documents`, com `recipients` e\n`documentType`, obrigatórios) ou pelo Modelo (`templateId`, com\n`fields` e `templateRoles`; o `documentType` e os `recipients` vêm do\nmodelo, e mandá-los é recusado). O pedido inteiro vai até 25 MB.\n", "oneOf": [ { "$ref": "#/components/schemas/NewEnvelopeFromDocuments" }, { "$ref": "#/components/schemas/NewEnvelopeFromTemplate" } ] }, "NewEnvelopeFromDocuments": { "type": "object", "title": "Pelo PDF", "required": [ "title", "documentType", "documents", "recipients" ], "additionalProperties": false, "properties": { "title": { "type": "string", "maxLength": 200 }, "documentType": { "$ref": "#/components/schemas/DocumentType" }, "externalReference": { "type": "string", "maxLength": 200, "description": "O id do registro no seu sistema. Não é única." }, "onBehalfOf": { "$ref": "#/components/schemas/OnBehalfOf" }, "status": { "type": "string", "enum": [ "draft", "sent" ], "default": "draft" }, "expiresInDays": { "type": "integer", "minimum": 2, "maximum": 999, "default": 30 }, "emailSubject": { "type": "string", "maxLength": 150 }, "message": { "type": "string", "maxLength": 2000, "description": "A mensagem a todos, no corpo do e-mail." }, "documents": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "required": [ "name", "contentBase64" ], "additionalProperties": false, "properties": { "name": { "type": "string", "maxLength": 200 }, "contentBase64": { "type": "string", "description": "O PDF em base64 — até 15 MB por arquivo, sem senha; passa pelo antivírus antes de gravar." } } } }, "recipients": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/NewRecipient" } } } }, "NewEnvelopeFromTemplate": { "type": "object", "title": "Pelo Modelo", "required": [ "templateId" ], "additionalProperties": false, "properties": { "templateId": { "type": "string", "format": "uuid" }, "title": { "type": "string", "maxLength": 200, "description": "Vazio usa o título do modelo." }, "externalReference": { "type": "string", "maxLength": 200, "description": "O id do registro no seu sistema. Não é única." }, "onBehalfOf": { "$ref": "#/components/schemas/OnBehalfOf" }, "status": { "type": "string", "enum": [ "draft", "sent" ], "default": "draft" }, "expiresInDays": { "type": "integer", "minimum": 2, "maximum": 999, "default": 30 }, "emailSubject": { "type": "string", "maxLength": 150 }, "message": { "type": "string", "maxLength": 2000, "description": "A mensagem a todos, no corpo do e-mail." }, "fields": { "type": "object", "description": "O valor de cada campo do modelo, pela key, como TEXTO na forma do tipo (`TemplateFieldType`).", "additionalProperties": { "type": [ "string", "boolean" ] } }, "templateRoles": { "type": "array", "items": { "$ref": "#/components/schemas/NewTemplateRole" } } } }, "Recipient": { "type": "object", "required": [ "id", "type", "order", "name", "email", "status", "sentAt", "deliveredAt", "signedAt", "declinedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/RecipientType" }, "order": { "type": "integer" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "$ref": "#/components/schemas/RecipientStatus" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Quando o e-mail com o link saiu de fato." }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time", "description": "A primeira vez que a pessoa confirmou o código e abriu." }, "signedAt": { "type": [ "string", "null" ], "format": "date-time" }, "declinedAt": { "type": [ "string", "null" ], "format": "date-time" } } }, "Envelope": { "type": "object", "description": "O CPF que a pessoa digitou não sai pela API — está no certificado de conclusão.", "required": [ "id", "title", "status", "test", "externalReference", "onBehalfOf", "documents", "recipients" ], "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": [ "string", "null" ], "example": "ENV0000042" }, "title": { "type": "string" }, "documentType": { "oneOf": [ { "$ref": "#/components/schemas/DocumentType" }, { "type": "null" } ] }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "statusChangedAt": { "type": [ "string", "null" ], "format": "date-time" }, "test": { "type": "boolean", "description": "Nasceu pela chave de teste: fora da cota, e o PDF concluído leva a tarja «TESTE — SEM VALIDADE»." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time", "description": "Muda a cada passo que a API mostra, do envelope ou de um destinatário." }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "voidedAt": { "type": [ "string", "null" ], "format": "date-time" }, "voidReason": { "type": [ "string", "null" ] }, "externalReference": { "type": [ "string", "null" ] }, "onBehalfOf": { "oneOf": [ { "$ref": "#/components/schemas/OnBehalfOf" }, { "type": "null" } ] }, "template": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "version": { "type": [ "integer", "null" ] } } }, { "type": "null" } ] }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sha256": { "type": "string" }, "sizeBytes": { "type": "integer" } } } }, "completedDocument": { "type": "object", "properties": { "available": { "type": "boolean" } } }, "certificate": { "type": "object", "properties": { "available": { "type": "boolean" } } }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } } } }, "EnvelopeSummary": { "type": "object", "required": [ "id", "title", "status", "updatedAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "statusChangedAt": { "type": [ "string", "null" ], "format": "date-time" }, "test": { "type": "boolean" }, "updatedAt": { "type": "string", "format": "date-time" }, "sentAt": { "type": [ "string", "null" ], "format": "date-time" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time" }, "externalReference": { "type": [ "string", "null" ] }, "onBehalfOf": { "oneOf": [ { "$ref": "#/components/schemas/OnBehalfOf" }, { "type": "null" } ] } } }, "Template": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "number": { "type": [ "string", "null" ] }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "documentType": { "oneOf": [ { "$ref": "#/components/schemas/DocumentType" }, { "type": "null" } ] }, "version": { "type": "integer" }, "supportedByApi": { "type": "boolean" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "$ref": "#/components/schemas/TemplateFieldType" }, "required": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" } } } } }, "roles": { "type": "array", "items": { "type": "object", "properties": { "order": { "type": "integer" }, "roleName": { "type": "string" }, "type": { "$ref": "#/components/schemas/RecipientType" }, "fixed": { "type": "boolean", "description": "A Cópia com nome e e-mail no modelo — não precisa vir no pedido." }, "nameFromField": { "type": [ "string", "null" ], "description": "A key do campo de onde vem o nome do SIGNER." }, "verifyCpfAtReceita": { "type": "boolean" }, "verifyCnpjAtReceita": { "type": "boolean" } } } } } }, "EventType": { "type": "string", "description": "Os eventos que se marcam no webhook. O `webhook.test` não se marca — só o «Enviar um teste» o manda.", "enum": [ "envelope.sent", "envelope.delivered", "recipient.signed", "recipient.declined", "envelope.completed", "envelope.declined", "envelope.voided", "envelope.expired" ] }, "DeliveryStatus": { "type": "string", "description": "pending (na fila, ou esperando a nova tentativa), delivered (o seu endereço respondeu 2xx), failed (desistimos).", "enum": [ "pending", "delivered", "failed" ] }, "Webhook": { "type": "object", "required": [ "id", "url", "description", "events", "enabled", "test", "disabledAt", "disabledReason", "failingSince", "lastSuccessAt", "lastAttemptAt", "secretRotatedAt", "previousSecretExpiresAt", "createdAt", "updatedAt" ], "properties": { "id": { "type": "string" }, "url": { "type": "string", "format": "uri", "example": "https://crm.example.com/webhooks/arcsign" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/EventType" } }, "enabled": { "type": "boolean" }, "test": { "type": "boolean", "description": "O ambiente: true = recebe só os eventos dos envelopes de teste, e só a chave de teste o vê. Vem da chave que o cadastrou." }, "disabledAt": { "type": [ "string", "null" ], "format": "date-time" }, "disabledReason": { "type": [ "string", "null" ], "description": "Por que se desligou — «Falhou por N dia(s) seguido(s)…», com o último erro, ou «Desligado à mão»." }, "failingSince": { "type": [ "string", "null" ], "format": "date-time", "description": "A primeira falha depois do último sucesso. Os dias de `webhook_retry_days` assim desligam o webhook." }, "lastSuccessAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "secretRotatedAt": { "type": [ "string", "null" ], "format": "date-time" }, "previousSecretExpiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Até quando o segredo anterior assina junto, depois de uma troca." }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "NewWebhook": { "type": "object", "required": [ "url", "events" ], "additionalProperties": false, "properties": { "url": { "type": "string", "maxLength": 2048, "description": "HTTPS, porta 443, endereço público." }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EventType" } }, "description": { "type": [ "string", "null" ], "maxLength": 200 } } }, "WebhookUpdate": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "url": { "type": "string", "maxLength": 2048 }, "events": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/EventType" } }, "description": { "type": [ "string", "null" ], "maxLength": 200 }, "enabled": { "type": "boolean" } } }, "Delivery": { "type": "object", "required": [ "id", "webhookId", "eventId", "eventType", "envelopeId", "status", "attempts", "nextAttemptAt", "lastAttemptAt", "lastResponseStatus", "lastError", "deliveredAt", "createdAt" ], "properties": { "id": { "type": "string" }, "webhookId": { "type": "string" }, "eventId": { "type": "string", "example": "evt_4f1c2b9a7e3d5c0a8b6f2e1d" }, "eventType": { "type": "string", "enum": [ "envelope.sent", "envelope.delivered", "recipient.signed", "recipient.declined", "envelope.completed", "envelope.declined", "envelope.voided", "envelope.expired", "webhook.test" ], "description": "Um EventType, ou webhook.test." }, "envelopeId": { "type": [ "string", "null" ], "description": "Nulo no webhook.test." }, "status": { "$ref": "#/components/schemas/DeliveryStatus" }, "attempts": { "type": "integer" }, "nextAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastAttemptAt": { "type": [ "string", "null" ], "format": "date-time" }, "lastResponseStatus": { "type": [ "integer", "null" ] }, "lastError": { "type": [ "string", "null" ], "example": "respondeu 500: Internal Server Error" }, "deliveredAt": { "type": [ "string", "null" ], "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } } }, "Event": { "type": "object", "description": "O corpo do aviso — MAGRO: o id e a fase do envelope, a sua referência e\no id do seu cliente; do destinatário, o id, o tipo, a ordem e a fase.\nNada de nome, e-mail nem CPF: o resto, busque pelo GET do envelope.\n", "required": [ "id", "type", "timestamp", "data" ], "properties": { "id": { "type": "string", "description": "O id do evento. Descarte o repetido por ele." }, "type": { "$ref": "#/components/schemas/EventType" }, "timestamp": { "type": "string", "format": "date-time", "description": "Quando o evento aconteceu." }, "data": { "type": "object", "required": [ "envelope", "recipient" ], "properties": { "envelope": { "type": "object", "required": [ "id", "status", "statusChangedAt", "externalReference", "onBehalfOf", "test" ], "properties": { "id": { "type": "string" }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "statusChangedAt": { "type": "string", "format": "date-time", "description": "Para ordenar os envelope.*: ignore o aviso mais velho que o último que você processou. Os recipient.* se ordenam pelo `timestamp`." }, "externalReference": { "type": [ "string", "null" ] }, "onBehalfOf": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] } } }, "test": { "type": "boolean", "description": "O envelope nasceu pela chave de teste." } } }, "recipient": { "type": [ "object", "null" ], "description": "Só nos recipient.*.", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/RecipientType" }, "order": { "type": "integer" }, "status": { "$ref": "#/components/schemas/RecipientStatus" } } } } } } }, "TestEvent": { "type": "object", "description": "O corpo do `webhook.test` — sem envelope. Responda 2xx a ele também.", "required": [ "id", "type", "timestamp", "data" ], "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "webhook.test" ] }, "timestamp": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "webhook" ], "properties": { "webhook": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "description": "O webhook que mandou o teste." } } } } } } } } } }