> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API Select do registo KYB: obter perfil da empresa > Chame POST /v3/kyb/select/ com um kyb_response_id da pesquisa no registo para obter o perfil completo e faturável da empresa na Didit. Use este endpoint depois de `POST /v3/kyb/search/` devolver empresas candidatas. O Select é o nível **Lite**: obtém o perfil da empresa e os seus administradores, sendo faturado ao preço Lite do país ([preços por país](https://docs.didit.me/pt/getting-started/kyb-registry-pricing.md)). Guarda o pedido como uma Manual Check na Business Console e devolve um `request_id` que pode usar para obter o resultado de verificação de empresas guardado. Para os acionistas ou os beneficiários efetivos finais, use [`POST /v3/kyb/shareholders/`](https://docs.didit.me/pt/standalone-apis/kyb-registry-shareholders) ou [`POST /v3/kyb/ubo/`](https://docs.didit.me/pt/standalone-apis/kyb-registry-ubo). A Didit aguarda que o registo de empresas de origem termine antes de responder, pelo que `fetch_status` é `resolved` na maioria das respostas. Se um registo lento mantiver o perfil pendente para além desse tempo de espera, a resposta devolve `fetch_status: pending` com `data_resolved: false`, e a Didit conclui automaticamente a verificação guardada assim que o fornecedor terminar. Volte a ler o resultado de verificação de empresas guardado em vez de repetir a pesquisa, porque uma nova pesquisa emite novos valores de `kyb_response_id`. ## OpenAPI ````yaml pt/openapi-25.json POST /v3/kyb/select/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de Verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/kyb/select/: post: tags: - Standalone APIs summary: Seleção de empresa no registo KYB — nível Lite (autónoma) description: >- Obtenha o perfil de registo **Lite** de um candidato retornado por `POST /v3/kyb/search/` — dados da empresa, morada registada, identificadores, estado, atividade e os administradores, além do payload em bruto do registo. Os acionistas e beneficiários efetivos são comercializados através de `POST /v3/kyb/shareholders/` e `POST /v3/kyb/ubo/`. **Associação à pesquisa.** Forneça o `kyb_response_id` do candidato exatamente como retornado por uma pesquisa da mesma aplicação. O identificador é efémero e restrito a essa pesquisa — selecione prontamente e efetue uma nova pesquisa para obter um novo identificador em vez de o armazenar. **Faturação.** Cada seleção é faturada ao preço Lite do país (qualquer taxa de pesquisa é cobrada em separado); consulte os [preços do registo KYB](/pt/getting-started/kyb-registry-pricing). O saldo é verificado antes de qualquer chamada ao registo (`403` quando insuficiente) e o débito é registado na sessão de empresa criada. **A persistência é obrigatória.** Cada seleção cria uma sessão de empresa (o seu id é o `request_id`) para que a faturação e a recuperação possam ser acompanhadas; fica visível na consola. `save_api_request` é aceite por simetria, mas tem de ser `true` (a predefinição) — o envio de `false` retorna `400`. operationId: post_v3_kyb_select parameters: [] requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KYBRegistryCandidateRequest' example: kyb_response_id: 69aeeb95febb0f1704042259 vendor_data: company-1234 responses: '200': description: >- Empresa obtida e faturada. O campo `kyb_registry` contém o perfil completo; verifique `data_resolved` — quando for `false`, o registo de empresas ainda estava em processamento e o registo guardado é concluído automaticamente assim que for resolvido. content: application/json: schema: type: object properties: request_id: type: string format: uuid description: >- ID da sessão de empresa criada para esta consulta. O registo guardado (visível na consola) continua a ser atualizado se a consulta ao registo for concluída após a resposta. registry_tier_requested: type: string enum: - basic - shareholders - ubo description: >- O nível que este endpoint comercializa: `basic` (Lite) para select, `shareholders`, `ubo`. registry_tier_delivered: type: string enum: - basic - shareholders - ubo description: >- O nível efetivamente entregue e faturado. Inferior ao solicitado quando os registos do país não contêm dados de propriedade ou quando o registo não tem qualquer registo de propriedade para esta empresa. kyb_registry: type: object description: Perfil completo da empresa no registo de empresas. properties: uuid: type: string format: uuid description: ID da Didit para este registo de empresa. node_id: type: string example: feature_kyb_registry status: type: string enum: - Not Finished - Approved - Declined - In Review description: >- Avaliação da Didit sobre a verificação do registo (por exemplo, `In Review` quando a empresa não está ativa no registo ou não foi possível obter os dados de propriedade). registry_status: type: string nullable: true enum: - active - dissolved - deregistered - see full details - authorised - appointed representative - unauthorised - inactive - no longer authorised - closed - struck off description: >- Estado normalizado da empresa conforme reportado pelo registo de empresas. data_resolved: type: boolean description: >- `true` assim que o registo tiver devolvido o perfil completo. `false` quando o registo ainda estava a processar após o polling — o registo guardado é concluído automaticamente assim que o registo ficar resolvido. company_name: type: string example: Tesco PLC registration_number: type: string nullable: true example: '00445790' country_code: type: string description: ISO 3166-1 alfa-2. example: GB region: type: string nullable: true description: >- Código de subdivisão quando o registo é regional (p. ex., `CA` para `US-CA`); vazio caso contrário. company_type: type: string nullable: true example: Public Limited Company incorporation_date: type: string format: date nullable: true example: '1947-11-27' registered_address: type: string nullable: true example: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: type: string nullable: true example: GB412 8925 93 risk_level: type: string nullable: true description: >- Nível de risco reportado pelo registo de empresas, quando disponível. verification_status: type: string enum: - verified - failed - unknown nullable: true description: >- Estado de verificação entre jurisdições: `verified` quando o estado do registo estabelece a regularidade da situação (`active`), `failed` quando indica que a empresa já não está em atividade (por exemplo `dissolved`), caso contrário `unknown`. `null` para uma empresa que não provenha de um registo e enquanto uma seleção estiver ainda `pending`. is_from_registry: type: boolean description: >- Sempre `true` para este endpoint — o perfil foi obtido a partir de um registo oficial. fetch_status: type: string enum: - pending - resolved description: >- Ciclo de vida de obtenção do registo de empresas. Espelhado por `data_resolved`. alternative_names: type: string nullable: true description: >- Nomes alternativos, comerciais, anteriores ou no idioma original da empresa em texto, quando comunicados. nature_of_business: type: string nullable: true description: >- Descrição da atividade ou código de classificação, quando comunicado. registered_capital: type: string nullable: true registered_capital_amount: type: string nullable: true description: Montante decimal como string, quando reportado. registered_capital_currency: type: string nullable: true description: Código ISO 4217, quando comunicado. website: type: string nullable: true example: https://www.tesco.com/ email: type: string nullable: true example: customer.service@tesco.co.uk phone: type: string nullable: true example: '03301231688' legal_entity_identifier: type: string nullable: true description: LEI, quando comunicado. location_of_registration: type: string nullable: true description: >- Registo de empresas/jurisdição onde a empresa está registada, quando reportado. vat_number: type: string nullable: true description: >- Número de IVA da UE, quando recolhido durante o passo de registo alojado ou editado posteriormente. No momento da seleção, normalmente ainda não está definido — a validação de IVA e do número de identificação fiscal é executada quando o utilizador final envia o passo de registo no fluxo alojado. vat_validation_status: type: string enum: - valid - invalid - format_valid - invalid_format - could_not_validate - not_applicable description: >- Resultado da validação do número de IVA ou, quando inexistente, do `tax_number`, no envio do registo. `valid` / `invalid`: decidido pelo registo oficial do país (VIES da UE, Noruega, Suíça, Brasil, Colômbia, Costa Rica, Equador, Paraguai; Polónia também pelo seu registo doméstico de IVA). `format_valid` / `invalid_format`: decidido pelas regras de formato e de dígito de controlo do país quando nenhum registo pode ser consultado. `could_not_validate`: o registo estava indisponível. `not_applicable`: sem número, um país sem registo ou regras, ou uma sessão de sandbox. vat_validated_number: type: string nullable: true description: >- O número que foi verificado, tal como a fonte o conhece (por exemplo, o número de IVA derivado de um SIREN francês ou de um RSIN neerlandês). `null` quando nenhuma verificação foi executada. vat_validation_source: type: string nullable: true enum: - eu_vies - pl_vat_white_list - no_brreg - ch_uid_register - br_receita_federal - co_rues - cr_hacienda - ec_sri - py_dnit - format_rules - null description: >- A origem que determinou o `vat_validation_status`: um registo oficial ou `format_rules`. `null` quando nenhuma verificação foi executada. vat_validated_name: type: string nullable: true description: >- Nome registado na fonte que validou o número, quando esta o divulga. Apenas definido quando o estado for `valid`. vat_validated_address: type: string nullable: true description: >- Morada registada junto da fonte que validou o número, quando esta a divulga. Apenas definida quando o estado é `valid`. vat_checked_at: type: string format: date-time nullable: true description: >- Carimbo de data/hora da verificação. `null` quando nenhuma verificação foi executada. financial_summary: type: object nullable: true description: >- Detalhes das ações/capital reportados pelo registo de empresas (moeda, total de ações, classes de ações), quando disponíveis. officers: type: array items: type: object properties: uuid: type: string format: uuid name: type: string example: MELISSA BETHELL designation: type: string nullable: true description: >- Designação no registo em bruto (por ex., `Director`, `Secretary`). role: type: string description: >- Função normalizada derivada da designação. Conjunto completo de 17 valores do modelo; a análise do registo de empresas neste endpoint emite tipicamente director, non_executive_director, secretary, chairman ou company_officer. enum: - director - non_executive_director - secretary - chairman - ubo - shareholder - representative - founder - legal_advisor - authorized_signatory - trustee - beneficiary - company_officer - settlor - protector - investor - other nationality: type: string nullable: true is_active: type: boolean description: >- `false` quando o registo marca a nomeação como tendo cessado. kyc_status: type: string nullable: true enum: - Approved - Declined - Pending description: >- Estado de uma sessão KYC associada, caso tenha sido iniciada uma para este administrador. Caso contrário, `null`. kyc_session_url: type: string nullable: true description: >- URL de verificação da sessão de KYC associada, quando existir. first_name: type: string nullable: true description: >- Nome próprio quando explicitamente indicado pelo registo; não deduzido a partir do nome completo. last_name: type: string nullable: true description: >- Apelido quando explicitamente comunicado pelo registo. address: type: string nullable: true description: Morada do administrador indicada pelo registo. appointment_date: type: string nullable: true description: Data em que o administrador foi nomeado. format: date termination_date: type: string nullable: true description: >- Data em que a nomeação terminou, quando reportada. format: date date_of_birth: type: string nullable: true description: >- Data de nascimento completa comunicada pelo registo de empresas. Nulo quando apenas o ano ou mês de nascimento é conhecido. format: date date_of_birth_year: type: integer nullable: true minimum: 1 maximum: 9999 description: >- Ano de nascimento reportado pelo registo de empresas, incluindo quando a data completa não está disponível. date_of_birth_month: type: integer nullable: true minimum: 1 maximum: 12 description: >- Mês de nascimento reportado pelo registo de empresas. Nulo quando apenas o ano é conhecido. description: >- Administradores, secretários e outros responsáveis extraídos do registo. beneficial_owners: type: array items: type: object properties: uuid: type: string format: uuid name: type: string first_name: type: string nullable: true last_name: type: string nullable: true entity_type: type: string enum: - person - company description: >- Se o proprietário é uma pessoa singular ou uma entidade coletiva. roles: type: array items: type: string description: >- Funções normalizadas (por exemplo, `ubo`, `shareholder`). ownership_min_shares: type: string nullable: true description: >- Limite inferior da faixa de propriedade reportada pelo registo (por exemplo, `25%`). ownership_max_shares: type: string nullable: true description: >- Limite superior do intervalo de propriedade reportado pelo registo. is_active: type: boolean kyc_status: type: string enum: - Approved - Declined - Pending nullable: true kyc_session_url: type: string nullable: true effective_ownership_percent: type: number nullable: true description: >- Percentagem de propriedade analisada (limite máximo, recorrendo ao limite mínimo como alternativa). company_name: type: string nullable: true registration_number: type: string nullable: true country_of_birth: type: string nullable: true email: type: string nullable: true nationality: type: string nullable: true designation: type: string nullable: true voting_min_shares: type: string nullable: true voting_max_shares: type: string nullable: true date_of_birth: type: string nullable: true description: Data de nascimento completa quando comunicada. format: date appointment_date: type: string nullable: true description: Data de nomeação quando comunicada. format: date shareholding: $ref: '#/components/schemas/KYBRegistryShareholding' description: >- Beneficiários efetivos / pessoas com controlo significativo extraídos do registo. Pode estar vazio quando o registo não divulga a propriedade. addresses: type: array nullable: true description: >- Todas as moradas indicadas pelo registo, num formato canónico. Nulo quando este não indicar nenhuma. items: $ref: '#/components/schemas/KYBRegistryAddress' industries: type: array nullable: true description: >- As atividades sob as quais o registo classifica a empresa, num formato canónico. Null quando não indica nenhuma. items: $ref: '#/components/schemas/KYBRegistryIndustry' accounts: type: object nullable: true additionalProperties: true description: >- Datas de submissão no registo de empresas, quando disponíveis. As declarações anuais e assembleias gerais utilizam last_annual_return_date e last_agm_date; são distintas das contas financeiras. registry_data: $ref: '#/components/schemas/KYBRegistryData' user_provided_data: type: object nullable: true description: >- Sempre `null` neste endpoint (utilizado pelo fluxo alojado de KYB quando os utilizadores finais editam dados do registo). confirmed_by_user_at: type: string format: date-time nullable: true description: Sempre `null` neste endpoint. last_console_edit_at: type: string format: date-time nullable: true description: >- Definido quando um revisor da consola edita o registo posteriormente. is_editable: type: boolean description: >- Se os dados provenientes do registo ainda podem ser editados no fluxo alojado/consola. registry_tier_delivered: type: string enum: - basic - shareholders - ubo description: Igual ao `registry_tier_delivered` de nível superior. registry_ownership_status: type: string nullable: true enum: - not_requested - delivered - not_held - unavailable description: >- `delivered` quando os dados de propriedade foram devolvidos, `not_held` quando o registo de propriedade respondeu e não lista esta empresa (consulte `registry_data.ownership_error`), `unavailable` quando um nível de propriedade foi solicitado mas o registo não tinha nenhum para esta empresa ou não pôde ser consultado (consulte `registry_data.ownership_error`), `not_requested` no nível Lite. ownership: $ref: '#/components/schemas/KYBRegistryOwnership' registry_tier: type: string nullable: true description: >- O nível de registo encomendado pelo fluxo: `basic`, `shareholders` ou `ubo`. Também em `ownership.tier_requested`. registry_monitoring: type: object nullable: true description: >- A monitorização mais recente do registo para a empresa, ou `null` quando não existir nenhuma. properties: uuid: type: string format: uuid status: type: string unavailable_reason: type: string nullable: true enrolled_at: type: string format: date-time nullable: true cancelled_at: type: string format: date-time nullable: true last_bill_date: type: string format: date nullable: true next_bill_date: type: string format: date nullable: true last_event_at: type: string format: date-time nullable: true events_count: type: integer watched_fields: description: Os campos da empresa que o monitor acompanha. vendor_data: type: string nullable: true description: Eco do `vendor_data` que enviou. metadata: type: object nullable: true description: Eco do objeto `metadata` que enviou. created_at: type: string format: date-time examples: Resolved company: summary: >- Perfil completo do registo de empresas (lista de administradores truncada para brevidade) value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d node_id: feature_kyb_registry status: In Review registry_status: active data_resolved: true company_name: Tesco PLC registration_number: '00445790' country_code: GB region: '' company_type: Public Limited Company incorporation_date: '1947-11-27' registered_address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA tax_number: GB412 8925 93 risk_level: low risk verification_status: verified is_from_registry: true fetch_status: resolved alternative_names: TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: https://www.tesco.com/ email: customer.service@tesco.co.uk phone: '03301231688' legal_entity_identifier: null location_of_registration: null financial_summary: currency: Pound (£) total_number_of_shares: '8174378721' meta_detail: Class_Of_Share: Ordinary officers: - uuid: a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b name: CHRISTOPHER JON TAYLOR designation: Secretary role: secretary nationality: null is_active: true kyc_status: null kyc_session_url: null - uuid: b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c name: MELISSA BETHELL designation: Director role: director nationality: British is_active: true kyc_status: null kyc_session_url: null beneficial_owners: [] addresses: - address: >- Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA type: legal_entity_registry_address description: registered office address industries: null accounts: last_account: 26 February 2025 next_account: 26 February 2026 due_by_date: 26 August 2026 registry_data: {} user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' Pending (registry still resolving): summary: >- A seleção permaneceu pendente após sondagem — campos esparsos, conclusão automática do lado do servidor value: request_id: 9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e kyb_registry: uuid: 7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d node_id: feature_kyb_registry status: Not Finished registry_status: null data_resolved: false company_name: Tesco PLC registration_number: '00445790' country_code: GB region: null company_type: null incorporation_date: null registered_address: null tax_number: null risk_level: null verification_status: null is_from_registry: true fetch_status: pending alternative_names: null nature_of_business: null registered_capital: null registered_capital_amount: null registered_capital_currency: null website: null email: null phone: null legal_entity_identifier: null location_of_registration: null financial_summary: {} officers: [] beneficial_owners: [] addresses: null industries: null accounts: null registry_data: {} user_provided_data: null confirmed_by_user_at: null last_console_edit_at: null is_editable: true vendor_data: company-1234 metadata: null created_at: '2026-06-11T10:45:00.000000+00:00' '400': description: >- Erro de validação. Problemas ao nível do campo utilizam o envelope padrão do DRF. Um país não abrangido pelos registos responde com `400` e `code: kyb_registry_country_unsupported`. content: application/json: examples: Missing kyb_response_id: summary: '`kyb_response_id` é obrigatório' value: kyb_response_id: - This field is required. save_api_request=false rejected: summary: As seleções são sempre persistidas value: save_api_request: - >- KYB registry select must be saved so billing and retrieval can be tracked. Country not covered: summary: Nenhum registo de empresas abrange o país value: detail: >- Company registry search is not available for this country. Enter the company details manually to continue. code: kyb_registry_country_unsupported '403': description: >- Permissão negada. Devolvido quando o cabeçalho `x-api-key` está em falta e também quando o saldo da organização que efetua a chamada não consegue cobrir a chamada; uma chave incorreta, revogada ou expirada devolve `401`. Uma chave em falta devolve `403` com `{"detail": ...}`; uma chave incorreta, revogada ou expirada devolve `401`. A insuficiência de créditos devolve `403` com `{"error": ...}` antes de qualquer triagem ou chamada ao fornecedor ocorrer. content: application/json: examples: Missing or invalid API key: summary: Sem cabeçalho `x-api-key`, ou a chave é inválida/revogada value: detail: You do not have permission to perform this action. Not enough credits: summary: O saldo da organização não cobre a chamada value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Limite de pedidos excedido. Os endpoints POST/PATCH/DELETE partilham um orçamento de 300 pedidos de escrita por minuto por chave de API (as criações de transações e a ingestão de eventos têm um orçamento separado de 600). A resposta inclui os cabeçalhos `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` e `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Mais de 300 pedidos de escrita no minuto atual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl source: |- curl -X POST https://verification.didit.me/v3/kyb/select/ \ -H 'x-api-key: YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" }' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.kyb.select( kyb_response_id="69aeeb95febb0f1704042259", vendor_data="company-1234", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.kyb.select({ kyb_response_id: "69aeeb95febb0f1704042259", vendor_data: "company-1234", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Select(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.KYBRegistryCandidateRequest; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.kyb().select(KYBRegistryCandidateRequest.builder() .kybResponseId("69aeeb95febb0f1704042259") .vendorData("company-1234") .build()); System.out.println(result); - lang: php label: PHP source: |- kyb->select([ 'kyb_response_id' => '69aeeb95febb0f1704042259', 'vendor_data' => 'company-1234', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.kyb.select( kyb_response_id: "69aeeb95febb0f1704042259", vendor_data: "company-1234" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Kyb.SelectAsync(new KYBRegistryCandidateRequest { KybResponseId = "69aeeb95febb0f1704042259", VendorData = "company-1234", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: KYBRegistryCandidateRequest: type: object required: - kyb_response_id properties: kyb_response_id: type: string maxLength: 1024 description: >- Identificador de candidato de `POST /v3/kyb/search/` (`kyb_registry.companies[].kyb_response_id`). Efémero: utilize-o pouco depois da pesquisa que o gerou. Os identificadores podem ser longos, pelo que deve armazenar e enviar o valor exatamente como devolvido, sem remover espaços em branco nem assumir um comprimento. example: 69aeeb95febb0f1704042259 vendor_data: type: string description: >- O seu identificador para esta empresa; devolvido e armazenado com a sessão da empresa. metadata: type: object nullable: true description: >- JSON de formato livre armazenado com a sessão de empresa e devolvido na resposta. save_api_request: type: boolean default: true description: >- Tem de ser `true` (o valor predefinido). As seleções de registo KYB são sempre persistidas para que a faturação e a recuperação possam ser monitorizadas; `false` devolve `400`. KYBRegistryShareholding: type: object nullable: true description: >- O que um proprietário detém, no mesmo formato para todos os países e fontes de registo. Nulo quando o registo não indicar qualquer participação. Um intervalo (por exemplo, os 25-50% de um PSC do Reino Unido) não é uma participação: `percentage` é nulo e o intervalo permanece em `ownership_min_shares` / `ownership_max_shares`. properties: share_class: type: string nullable: true description: Classe ou tipo de ação conforme designado no registo. number_of_shares: type: number nullable: true description: Número de ações detidas. currency: type: string nullable: true description: Moeda ISO 4217 dos valores abaixo. nominal_value: type: number nullable: true description: Valor nominal por ação. total_value: type: number nullable: true description: Valor total da posição detida. percentage: type: number nullable: true description: Participação exata em percentagem, até quatro casas decimais. required: - share_class - number_of_shares - currency - nominal_value - total_value - percentage KYBRegistryAddress: type: object description: >- Uma morada indicada pelo registo, com o mesmo formato para todos os países e fontes de registo. Todas as chaves estão sempre presentes; uma parte que o registo não publique é null. properties: type: type: string nullable: true description: >- Tipo de morada em minúsculas: `registered` para a sede social; outros tipos conforme designados pelo registo (por exemplo, `postal`, `office`). `null` quando o registo não indica o tipo de morada. address: type: string description: A morada completa numa linha. Sempre presente em todas as moradas. street: type: string nullable: true description: Rua e número. city: type: string nullable: true description: Cidade ou localidade. postal_code: type: string nullable: true description: Código postal. region: type: string nullable: true description: Região, estado ou província. country_code: type: string nullable: true description: Código de país ISO 3166-1 alpha-2. description: type: string nullable: true description: A etiqueta própria do registo para a morada, quando este a fornece. required: - type - address - street - city - postal_code - region - country_code - description KYBRegistryIndustry: type: object description: >- Uma atividade na qual o registo classifica a empresa, com o mesmo formato para todos os países e fontes de registo. properties: code: type: string nullable: true description: >- Código de atividade conforme consta do registo (por exemplo `73110`). description: type: string nullable: true description: Rótulo da atividade, quando o registo publica um. scheme: type: string nullable: true description: >- Sistema de classificação, um nome por sistema independentemente da fonte que o comunicou: `UK SIC 2007`, `US SIC`, `NACE Rev. 2`, `NACE Rev. 2.1`, `NAF Rev. 2`, `CNAE`, `SBI`, `NOGA 2008`, `CAE Rev. 4`, `Canada SIC 1977`; outros sistemas nacionais mantêm o nome original do registo. Nulo quando o registo não especifica o sistema. is_primary: type: boolean description: >- True para a atividade principal da empresa. Exatamente uma entrada é principal quando a lista não está vazia. required: - code - description - scheme - is_primary KYBRegistryData: type: object nullable: true description: >- Detalhe de registo normalizado da Didit para a empresa: o resultado da propriedade (`ownership_error`, `section_errors`, `ubo_resolution`, `lite_enrichment`), as correções feitas com update-data e factos de registo que não têm um campo próprio. Nunca transporta o registo próprio da fonte de registo. Todas as chaves são opcionais e estão presentes apenas quando a empresa tem um valor para as mesmas; podem ser adicionadas novas chaves. Leia os campos canónicos (`addresses`, `industries`, `ownership`, `beneficial_owners[].shareholding`) para tudo o que abrangem. properties: company_name: type: string description: Nome da empresa conforme corrigido na consola. registration_number: type: string description: >- Número de registo conforme indicado pelo registo de empresas ou por uma correção na consola. country_code: type: string description: >- País do registo conforme indicado pelo registo de empresas ou por uma correção na consola. region: type: string description: Região ou estado do registo. incorporation_date: type: string description: Data de constituição (ISO 8601). registration_date: type: string description: >- Data de registo (ISO 8601) quando o registo de empresas indica uma diferente da data de constituição. dissolution_date: type: string description: Data de dissolução (ISO 8601) quando o registo a indicar. tax_number: type: string description: Número de identificação fiscal. vat_number: type: string description: Número de IVA (NIF). legal_address: type: string description: Sede social conforme corrigida na consola. registered_address: type: string description: Morada registada conforme indicada no registo. company_type: type: string description: Forma jurídica. registry_status: type: string description: Estado da empresa no registo de empresas. verification_status: type: string description: Estado da verificação. alternative_names: type: string description: Outros nomes com os quais a empresa opera ou operou. nature_of_business: type: string description: Descrição da atividade. registered_capital: type: string description: Capital social registado conforme impresso. registered_capital_amount: type: string description: >- Montante do capital social registado, como cadeia de caracteres decimal. registered_capital_currency: type: string description: Moeda do capital social registado (ISO 4217). website: type: string description: Website. email: type: string description: E-mail de contacto. phone: type: string description: Telefone de contacto. legal_entity_identifier: type: string description: Identificador de Entidade Jurídica (LEI). location_of_registration: type: string description: Local de registo. control_scheme: type: string description: Regime de governação quando o registo o disponibiliza. ownership_error: type: string enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other description: >- O motivo pelo qual um nível de propriedade solicitado não foi fornecido, nos mesmos códigos que `ownership.unavailable_reason`. `no_owners_on_record` (o registo respondeu e não indica nenhum proprietário) e `ownership_section_unavailable` (o registo não devolveu a secção de propriedade) são conclusões diferentes. section_errors: type: object description: >- Secções que o registo não devolveu, indexadas por secção (`officers`, `shareholders`, `group_structure`). Uma secção listada aqui nunca foi entregue: uma lista vazia ao lado não diz nada sobre a empresa. additionalProperties: $ref: '#/components/schemas/KYBRegistrySectionError' ubo_resolution: $ref: '#/components/schemas/KYBRegistryUboResolution' lite_enrichment: $ref: '#/components/schemas/KYBRegistryLiteEnrichment' registry_metadata: type: object additionalProperties: oneOf: - type: string - type: number - type: boolean description: >- Os campos próprios do registo para a empresa, indexados tal como o registo os nomeia, como valores simples (registos legados). Apenas estão incluídos os campos revistos como factos do registo. registry_sources: type: array description: >- Os registos oficiais a partir dos quais o registo foi lido (registos legados). Outras fontes não são indicadas. items: $ref: '#/components/schemas/KYBRegistrySource' previous_names: type: array items: type: string description: >- Nomes sob os quais a empresa esteve registada anteriormente (registos históricos). parent_companies: type: array items: type: string description: Empresas-mãe identificadas pelo registo (registos legados). documents_available: type: integer description: >- Quantos registos o registo disponibiliza para a empresa (registos legados). KYBRegistryOwnership: type: object description: >- O resultado do nível de propriedade (Acionistas / UBO), no mesmo formato para todos os países e fontes de registo. properties: status: type: string nullable: true enum: - not_requested - pending - delivered - not_held - unavailable - null description: >- `delivered` quando o registo disponibilizou os dados de propriedade; `not_held` quando o registo de propriedade respondeu e não lista de todo a empresa (consulte `unavailable_reason`); `unavailable` quando não disponibilizou os dados de propriedade por qualquer outro motivo (consulte `unavailable_reason`); `pending` enquanto o registo ainda os estiver a obter; `not_requested` para o nível Basic. tier_requested: type: string nullable: true enum: - basic - shareholders - ubo - null description: O nível encomendado pelo fluxo. tier_delivered: type: string nullable: true enum: - basic - shareholders - ubo - null description: >- O nível entregue pelo registo (e que é faturado). Um pedido de UBO respondido apenas com acionistas diretos é `shareholders`. unavailable_reason: type: string nullable: true enum: - no_owners_on_record - no_natural_person_owner - ownership_section_unavailable - company_not_found - ambiguous_company_match - missing_registration_number - entity_type_not_covered - provider_unavailable - other - null description: >- O motivo pelo qual um nível de propriedade solicitado não foi fornecido. Nulo, exceto se `status` for `unavailable` ou `pending`. direct_ownership_complete: type: boolean nullable: true description: >- True quando as participações declaradas dos acionistas diretos perfazem 100% (dentro de uma margem de arredondamento de um ponto percentual); false quando não perfazem; null quando a propriedade não foi fornecida ou uma participação não está declarada. unresolved: type: array description: >- Partes da cadeia de propriedade que o registo não conseguiu resolver, por exemplo, a ausência de registo da estrutura do grupo acima dos proprietários diretos. items: type: object properties: reason: type: string section: type: string nullable: true required: - status - tier_requested - tier_delivered - unavailable_reason - direct_ownership_complete - unresolved KYBRegistrySectionError: type: object description: Uma secção que o registo não devolveu. properties: status_code: type: integer nullable: true description: O estado retornado pelo registo para a secção. required: - status_code KYBRegistryUboResolution: type: object description: Como o nível de UBO percorreu a cadeia de propriedade acima da empresa. properties: parent_chain: type: array description: Empresas-mãe desde a entidade-mãe final até à empresa. items: $ref: '#/components/schemas/KYBRegistryGroupCompany' subsidiaries: type: array description: Empresas diretamente abaixo da empresa no seu grupo empresarial. items: $ref: '#/components/schemas/KYBRegistryGroupCompany' unresolved: type: array description: >- Partes da cadeia que o registo não conseguiu resolver (as mesmas entradas que `ownership.unresolved`). items: type: object properties: reason: type: string description: >- O motivo, por exemplo `no_group_structure_on_record`, `selected_company_not_in_group_structure` ou `section_error`. section: type: string nullable: true description: A secção em causa, por exemplo `group_structure`. required: - reason - section required: - parent_chain - subsidiaries - unresolved KYBRegistryLiteEnrichment: type: object description: >- Campos vazios do perfil Lite que outra das fontes de registo do país preencheu. A fonte não é indicada. properties: fields: type: array items: type: string description: Os campos da empresa que foram preenchidos. people_added: type: integer description: Quantos administradores ou proprietários foram adicionados. required: - fields - people_added KYBRegistrySource: type: object description: >- Um registo oficial a partir do qual os dados foram obtidos. Apenas são nomeados registos governamentais oficiais, reguladores e o sistema oficial de identificadores; qualquer outra fonte é omitida. properties: name: type: string description: Nome do registo, por exemplo `UK Companies House`. source_type: type: string enum: - official description: Sempre `official`. required: - name - source_type KYBRegistryGroupCompany: type: object description: Uma empresa do grupo empresarial, pela sua identidade de registo. properties: name: type: string nullable: true description: Nome da empresa. country_code: type: string nullable: true description: País de registo. registration_number: type: string nullable: true description: Número de registo. required: - name - country_code - registration_number securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está incorreta, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. Consulte https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.