{"openapi":"3.1.0","info":{"title":"Titus Docs · API de integração","version":"1.0.0","description":"Crie recolhas de documentos oficiais a partir do seu CRM e receba o link para enviar ao cliente. Autenticação por chave Bearer criada no Escritório Virtual (Chaves de API). POST /recolhas exige Idempotency-Key: repetir com a mesma chave e o mesmo corpo devolve a mesma resposta; com outro corpo dá 409. Webhooks: evento recolha.completed, assinado com HMAC SHA-256 no cabeçalho X-TitusDocs-Signature (t=<unix>,v1=<hex>, sobre `${t}.${corpo}`). As entregas falhadas são repetidas com espera crescente (até 8 tentativas); deduplique por X-TitusDocs-Delivery ou por event+recolhaId."},"servers":[{"url":"https://docs.titusone.pt"}],"components":{"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","description":"Chave td_live_… criada em Escritório Virtual → Chaves de API."}},"schemas":{"DocumentType":{"type":"object","required":["value","source","kind","name","description"],"properties":{"value":{"type":"string","examples":["certidao-domicilio-fiscal"]},"source":{"type":"string","enum":["AT","SS","BdP","IRN","ADENE","AIMA","IMT"]},"kind":{"type":"string","enum":["collect","template"],"description":"collect = recolhido por robô; template = modelo oficial em PDF"},"name":{"type":"string"},"description":{"type":"string"}}},"CreateRecolhaRequest":{"type":"object","required":["client","documents"],"properties":{"requester":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Membro da organização que fica como autor."}}},"client":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"nif":{"type":"string"},"notes":{"type":"string"},"externalId":{"type":"string","description":"O id do cliente no seu CRM (usado para encontrar o mesmo cliente)."},"updateIfExists":{"type":"boolean","default":false}}},"documents":{"type":"array","items":{"type":"string"},"minItems":1},"notes":{"type":"string","description":"Nota que o cliente vê no link."},"reference":{"type":"string","description":"Referência interna."},"locale":{"type":"string","default":"pt"},"expiresInDays":{"type":"integer","minimum":1,"maximum":30,"default":7},"delivery":{"type":"object","properties":{"webhookId":{"type":"string","format":"uuid"}}}}},"CreateRecolhaResponse":{"type":"object","required":["recolhaId","seqId","clientId","status","paymentMode","shareUrl"],"properties":{"recolhaId":{"type":"string","format":"uuid"},"seqId":{"type":"integer"},"clientId":{"type":"string","format":"uuid"},"status":{"type":"string"},"paymentMode":{"type":"string","enum":["credits"]},"shareUrl":{"type":"string","format":"uri"},"expiresAt":{"type":["string","null"],"format":"date-time"}}},"Recolha":{"type":"object","properties":{"recolhaId":{"type":"string"},"seqId":{"type":"integer"},"clientId":{"type":["string","null"]},"status":{"type":"string","enum":["criada","aberta","em_curso","concluida","parcial","falhou","expirada","cancelada"]},"shareUrl":{"type":"string"},"createdAt":{"type":"string"},"authorizedAt":{"type":["string","null"]},"completedAt":{"type":["string","null"]},"documents":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"status":{"type":"string","enum":["pendente","em_curso","obtido","sem_dados","erro","nao_aplicavel","modelo"]},"message":{"type":["string","null"]},"files":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"bytes":{"type":"integer"},"sha256":{"type":"string"},"url":{"type":"string"}}}}}}}}},"WebhookRecolhaCompleted":{"type":"object","properties":{"event":{"const":"recolha.completed"},"recolhaId":{"type":"string"},"seqId":{"type":"integer"},"clientId":{"type":["string","null"]},"status":{"type":"string"},"completedAt":{"type":"string"},"documents":{"$ref":"#/components/schemas/Recolha/properties/documents"}}},"Error":{"type":"object","required":["error","code"],"properties":{"error":{"type":"string"},"code":{"type":"string"}}}}},"security":[{"ApiKeyBearer":[]}],"paths":{"/api/v1/integrations/document-types":{"get":{"summary":"Lista os tipos de documento disponíveis","parameters":[{"name":"locale","in":"query","schema":{"type":"string","default":"pt"}},{"name":"kind","in":"query","schema":{"type":"string","enum":["collect","template"]}}],"responses":{"200":{"description":"Catálogo","content":{"application/json":{"schema":{"type":"object","properties":{"documents":{"type":"array","items":{"$ref":"#/components/schemas/DocumentType"}}}}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Falha temporária","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integrations/recolhas":{"post":{"summary":"Cria uma recolha e devolve o link para o cliente","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecolhaRequest"}}}},"responses":{"201":{"description":"Recolha criada","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRecolhaResponse"}}}},"400":{"description":"Pedido inválido (invalid_documents, invalid_client, missing_idempotency_key…)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"insufficient_scope ou requester_not_approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict ou idempotency_in_progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Falha ao criar (pode repetir com a mesma Idempotency-Key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Falha temporária","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integrations/recolhas/{id}":{"get":{"summary":"Estado de uma recolha, documento a documento, com os ficheiros","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Recolha","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recolha"}}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/integrations/recolhas/{id}/files/{fileId}":{"get":{"summary":"Descarrega um ficheiro (PDF) da recolha","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"fileId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"O ficheiro","content":{"application/pdf":{}}},"401":{"description":"invalid_api_key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"webhooks":{"recolha.completed":{"post":{"summary":"A recolha terminou (concluida, parcial ou falhou)","parameters":[{"name":"X-TitusDocs-Signature","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-TitusDocs-Event","in":"header","required":true,"schema":{"type":"string"}},{"name":"X-TitusDocs-Delivery","in":"header","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookRecolhaCompleted"}}}},"responses":{"200":{"description":"Responda 2xx para confirmar."}}}}}}