> ## Documentation Index > Fetch the complete documentation index at: https://docs.niadra.com/llms.txt > Use this file to discover all available pages before exploring further. # Reivindicar um cliente ou uma tarefa > Uma posse (`owner`, `case`) sobre o cliente ou uma trava de tarefa sobre um objeto, por um prazo; recusada com 409 enquanto outro detentor tem uma reivindicação igual ou mais restritiva. Uma observação do seu worker nunca é recusada. ## OpenAPI ````yaml openapi/pt/cell.json POST /v1/coordination/claims openapi: 3.1.0 info: title: API de dados da Niadra version: '1' description: >- Escrita, contexto, histórico, objetos, identidade, privacidade e governança de um espaço. Cada espaço tem um endereço estável, com o espaço e a região no nome. servers: - url: https://{space}.{region}.api.niadra.com variables: space: default: acme-prod description: O espaço, que vem na chave de fonte. region: default: us-east-2 description: A região do espaço, que também vem na chave. security: [] paths: /v1/coordination/claims: post: tags: - coordination summary: Reivindicar um cliente ou uma tarefa description: >- Declara uma reivindicação sobre o cliente (`owner` ou `case`, num nível do espaço, por um prazo) ou uma trava de tarefa sobre um objeto de negócio. A reivindicação válida mais restritiva detém o alvo; uma declaração é recusada enquanto a de outro detentor é ao menos tão restritiva (409 `lease_held`), e o mesmo detentor renova a própria. Com `source`, é uma observação que o worker da empresa leu de uma das fontes de posse do espaço: nunca recusada, ela substitui o que a fonte disse antes, limitada pela validade da fonte. **Autenticação.** Chave de fonte: `Authorization: Bearer nia_sk_...`. Escopo exigido: `coordinate`. Só responde num espaço com a funcionalidade `coordination` ligada (o documento `features`); num espaço sem ela, 404. operationId: claim_v1_coordination_claims_post parameters: - in: header name: Idempotency-Key required: true schema: maxLength: 256 minLength: 1 title: Idempotency-Key type: string description: >- Obrigatório. Guardado por 24 horas com o hash do corpo: a mesma chave com o mesmo corpo devolve a primeira resposta, e a mesma chave com outro corpo devolve 409 `conflict`. requestBody: content: application/json: schema: $ref: '#/components/schemas/ClaimRequest' required: true responses: '201': content: application/json: schema: $ref: '#/components/schemas/OwnershipClaim' description: A reivindicação, com a época que uma liberação precisa nomear. '409': description: '`lease_held`, com o detentor e até quando.' '422': content: application/problem+json: schema: $ref: '#/components/schemas/Problem' description: O pedido não bate com o contrato. security: - sourceKey: [] x-codeSamples: - lang: python label: Python source: >- # Hold the customer while this agent works the case; another holder's stricter claim wins claimed = conversation.claim(kind="case", lease_s=600, intents=["proposal_followup"]) if not claimed.held: print(claimed.error) # lease_held, task_locked, or Niadra did not answer - lang: typescript label: TypeScript source: >- // Hold the customer while this agent works the case; another holder's stricter claim wins const claimed = await convo.claim({ kind: "case", leaseS: 600, intents: ["proposal_followup"] }); if (!claimed.held) console.log(claimed.error); // lease_held, task_locked, or Niadra did not answer components: schemas: ClaimRequest: additionalProperties: false description: >- Uma reivindicação declarada, detida por `holder`. `level` é por padrão o nível menos restritivo do espaço; uma declaração é recusada (409 `lease_held`) enquanto a reivindicação de outro detentor é ao menos tão restritiva, e o mesmo detentor renova a própria. `lease_s` é limitado pelo maior prazo declarado do espaço. Uma trava de tarefa nomeia um objeto e a `task` dele, e é recusada (409 `task_locked`) enquanto outro detentor tem essa tarefa. properties: holder: maxLength: 256 minLength: 1 title: Holder type: string intents: items: pattern: ^[a-z][a-z0-9_]{0,39}$ type: string maxItems: 20 title: Intents type: array kind: $ref: '#/components/schemas/ClaimKind' lease_s: maximum: 86400 minimum: 1 title: Lease S type: integer level: anyOf: - pattern: ^[a-z][a-z0-9_]{0,39}$ type: string - type: 'null' title: Level object: anyOf: - $ref: '#/components/schemas/ObjectRef' - type: 'null' observed_at: anyOf: - format: date-time type: string - type: 'null' description: >- Quando a fonte viu; uma observação mais antiga que a última da fonte é ignorada. title: Observed At source: anyOf: - pattern: ^[a-z][a-z0-9_]{0,39}$ type: string - type: 'null' description: >- Uma observação desta fonte de posse, lida e enviada pelo worker da empresa: nunca recusada, substitui o que a fonte disse antes, limitada pela validade da fonte. title: Source subject: anyOf: - $ref: '#/components/schemas/Handle' - type: 'null' task: anyOf: - pattern: ^[a-z][a-z0-9_]{0,39}$ type: string - type: 'null' title: Task required: - kind - holder - lease_s title: ClaimRequest type: object OwnershipClaim: additionalProperties: false properties: claim_id: maxLength: 512 minLength: 1 title: Claim Id type: string epoch: title: Epoch type: integer holder: title: Holder type: string kind: $ref: '#/components/schemas/ClaimKind' level: pattern: ^[a-z][a-z0-9_]{0,39}$ title: Level type: string valid_until: format: date-time title: Valid Until type: string required: - claim_id - kind - holder - level - valid_until - epoch title: OwnershipClaim type: object Problem: additionalProperties: false description: >- Detalhes do problema no formato da RFC 9457; `code` vem do catálogo de erros versionado. properties: code: title: Code type: string detail: anyOf: - type: string - type: 'null' default: null title: Detail request_id: anyOf: - type: string - type: 'null' default: null title: Request Id status: title: Status type: integer title: title: Title type: string type: default: about:blank title: Type type: string required: - title - status - code title: Problem type: object ClaimKind: enum: - owner - case - task_lock title: ClaimKind type: string ObjectRef: additionalProperties: false description: Um objeto de negócio num sistema de registro. properties: id: maxLength: 512 minLength: 1 title: Id type: string description: O id nesse sistema. namespace: maxLength: 256 minLength: 1 title: Namespace type: string description: O sistema onde ele vive, como `erp`. type: maxLength: 256 minLength: 1 title: Type type: string description: Tipo do objeto, como `invoice`, `order` ou `ticket`. required: - type - namespace - id title: ObjectRef type: object Handle: additionalProperties: false description: >- Um identificador de um sujeito num canal ou sistema: um telefone, um e-mail, um id do CRM. properties: scope: anyOf: - maxLength: 256 minLength: 1 type: string - type: 'null' description: >- Espaço de nomes dos identificadores com escopo: a conta do WhatsApp Business para `wa_bsuid`, o sistema para `system_id`, o país para `gov_id_hmac`. title: Scope subject_kind: anyOf: - $ref: '#/components/schemas/SubjectKind' - type: 'null' description: >- O padrão é `person`, exceto nos tipos de handle que só identificam organizações. type: $ref: '#/components/schemas/HandleType' value: maxLength: 320 minLength: 1 title: Value type: string description: >- O identificador. Normalizado no servidor: E.164 para telefone, minúsculas para e-mail. required: - type - value title: Handle type: object SubjectKind: enum: - person - account - partner title: SubjectKind type: string description: >- Uma pessoa, uma organização cliente (`account`) ou uma organização que participa sem ser cliente (`partner`). HandleType: enum: - phone_e164 - wa_id - wa_jid - wa_lid - wa_bsuid - email - gov_id_hmac - app_user_id - system_id - org_registry_hmac - email_domain - anon_id title: HandleType type: string description: >- O tipo de identificador. O valor é classificado pelo formato, nunca pelo campo de onde veio. securitySchemes: sourceKey: type: http scheme: bearer description: nia_sk_... ````