> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firma.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Finalizar configuración del dominio del espacio de trabajo

> Finaliza la configuración del dominio registrándolo con el proveedor de correo electrónico. Esto devuelve los registros DNS (SPF, DKIM, DMARC) que deben agregarse para habilitar el envío de correo electrónico. Solo se puede llamar después de que se verifique la propiedad del dominio.



## OpenAPI

````yaml api-reference/v01.30.00/openapi-v01.30.00.es.json post /workspace/{workspace_id}/domains/{id}/finalize
openapi: 3.0.3
info:
  title: API de Socios de Firma
  description: >-
    API RESTful para firma de documentos y gestión de plantillas.


    **Autenticación**: Todos los endpoints requieren autenticación mediante
    clave API a través del encabezado `Authorization`. Usa tu clave API
    directamente sin ningún prefijo (por ejemplo, `your-api-key`). El prefijo
    Bearer es opcional pero no obligatorio.


    **Características de Seguridad**:

    - Validación de entrada usando esquemas Zod con mensajes de error detallados
    a nivel de campo

    - Tokens JWT firmados con RSA-256 para el acceso al Editor de Plantillas
    incrustado


    **Límite de Solicitudes**: Los límites de solicitudes están escalonados
    según el tipo de operación:

    - Operaciones de lectura (GET): 200 solicitudes por minuto

    - Operaciones de escritura (POST/PUT/PATCH/DELETE): 120 solicitudes por
    minuto

    - Operaciones CRUD de webhooks: 60 solicitudes por minuto

    - Prueba de webhook: 10 solicitudes por minuto

    - Regeneración/expiración de clave API: 1 solicitud por minuto

    - Rotación de secreto de webhook: 1 solicitud por minuto


    Cuando se superan los límites de solicitudes, la API devuelve una respuesta
    `429 Too Many Requests` con los encabezados:

    - `X-RateLimit-Limit`: Máximo de solicitudes por minuto para este endpoint

    - `X-RateLimit-Remaining`: Solicitudes restantes en la ventana actual

    - `X-RateLimit-Reset`: Marca de tiempo Unix de cuándo se restablece el
    límite

    - `Retry-After`: Segundos hasta que se permita reintentar


    **Manejo de Errores**: Todos los errores devuelven respuestas JSON
    estructuradas con `error` (mensaje legible para humanos), `code`
    (identificador legible por máquina) y `details` (errores de validación a
    nivel de campo cuando corresponda).


    **Integración del Editor de Plantillas Incrustado**: El Editor de Plantillas
    de Firma se puede incrustar en tu aplicación usando una biblioteca
    JavaScript independiente.


    ```html

    <!-- Carga la biblioteca del Editor de Plantillas de Firma -->

    <script
    src="https://api.firma.dev/functions/v1/embed-proxy/template-editor.js"></script>


    <script>

    // Genera el token JWT vía API primero

    fetch('https://api.firma.dev/functions/v1/signing-request-api/generate-template-token',
    {
      method: 'POST',
      headers: {
        'Authorization': 'YOUR_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        companies_workspaces_templates_id: 'template-id'
      })
    })

    .then(res => res.json())

    .then(data => {
      // Inicializa el editor con el token JWT
      window.FirmaTemplateEditor.init({
        container: '#firma-editor-container',
        jwt: data.token,
        templateId: 'template-id',
        theme: 'dark',
        readOnly: false,
        onSave: (savedData) => {
          console.log('Template saved:', savedData);
        },
        onError: (error) => {
          console.error('Editor error:', error);
        },
        onLoad: (template) => {
          console.log('Template loaded:', template);
        }
      });
    });

    </script>

    ```
  version: 01.30.00
  contact:
    name: API Support
    url: https://firma.com/support
servers:
  - url: https://api.firma.dev/functions/v1/signing-request-api
    description: API de Producción - Recomendada (Actual)
  - url: https://api.firma.dev/api/v1
    description: API de Producción - Planeada
security:
  - ApiKeyAuth: []
tags:
  - name: Company
    description: Información y configuración de la empresa
  - name: Workspaces
    description: Operaciones de gestión de espacios de trabajo
  - name: Templates
    description: Operaciones de gestión de plantillas
  - name: Signing Requests
    description: Operaciones de solicitudes de firma de documentos
  - name: Custom Fields
    description: >-
      Gestión de definiciones de campos personalizados para espacios de trabajo,
      plantillas y solicitudes de firma
  - name: Webhooks
    description: Configuración y gestión de webhooks
  - name: JWT Management
    description: Generación y revocación de tokens JWT para plantillas incrustadas
  - name: Workspace Settings
    description: Configuración y ajustes del espacio de trabajo
  - name: Email Domains
    description: >-
      Configuración y verificación de dominios de correo electrónico para enviar
      correos de solicitudes de firma desde dominios personalizados
  - name: Email Templates
    description: >-
      Gestión de plantillas de correo electrónico para personalización de
      notificaciones de solicitudes de firma a nivel de espacio de trabajo y de
      empresa
  - name: Signer Terms
    description: >-
      Términos de servicio / declaraciones de consentimiento personalizadas del
      firmante, a nivel de empresa con anulaciones por espacio de trabajo según
      el idioma
paths:
  /workspace/{workspace_id}/domains/{id}/finalize:
    post:
      tags:
        - Email Domains
      summary: Finalizar configuración del dominio del espacio de trabajo
      description: >-
        Finaliza la configuración del dominio registrándolo con el proveedor de
        correo electrónico. Esto devuelve los registros DNS (SPF, DKIM, DMARC)
        que deben agregarse para habilitar el envío de correo electrónico. Solo
        se puede llamar después de que se verifique la propiedad del dominio.
      operationId: finalizeWorkspaceDomain
      parameters:
        - name: workspace_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID del espacio de trabajo
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: ID del dominio
      responses:
        '200':
          description: >-
            Dominio finalizado correctamente. Agrega los registros DNS
            devueltos.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DomainFinalizeResponse'
              example:
                message: >-
                  Domain finalized. Add the following DNS records to enable
                  email sending.
                domain:
                  id: 123e4567-e89b-12d3-a456-426614174000
                  domain: sales.acme.com
                  verification_status: 2
                  domain_status: 0
                dns_records:
                  - type: TXT
                    name: '@'
                    value: v=spf1 include:amazonses.com ~all
                    ttl: Auto
                    status: pending
                  - type: CNAME
                    name: resend._domainkey
                    value: resend._domainkey.amazonses.com
                    ttl: Auto
                    status: pending
                  - type: TXT
                    name: _dmarc
                    value: v=DMARC1; p=none;
                    ttl: Auto
                    status: pending
                next_step: >-
                  Add these DNS records, then call POST
                  /workspace/{workspace_id}/domains/{id}/verify-dns to complete
                  verification
        '400':
          description: No se puede finalizar
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                notVerified:
                  value:
                    error: Ownership not verified
                    message: >-
                      Please verify domain ownership first by calling POST
                      /workspace/{workspace_id}/domains/{id}/verify-ownership
                alreadyFinalized:
                  value:
                    error: Already finalized
                    message: Domain has already been finalized
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '429':
          $ref: '#/components/responses/RateLimitError'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: TypeScript
          label: '@firma-dev/sdk'
          source: |-
            import { FirmaClient } from "@firma-dev/sdk";

            const firma = new FirmaClient({ apiKey: "YOUR_API_KEY" });

            const response = await firma.emailDomains.finalizeWorkspaceDomain({
                workspace_id: "workspace_id",
                id: "id"
            });
            console.log(response);
components:
  schemas:
    DomainFinalizeResponse:
      type: object
      properties:
        message:
          type: string
        domain:
          $ref: '#/components/schemas/Domain'
        dns_records:
          type: array
          items:
            $ref: '#/components/schemas/DomainDnsRecord'
          description: Registros DNS a agregar para el envío de emails
        next_step:
          type: string
      description: Finalización del dominio con registros DNS
      required:
        - message
        - domain
        - dns_records
        - next_step
    Error:
      type: object
      properties:
        error:
          type: string
          description: Mensaje de error legible para humanos
        message:
          type: string
          description: Descripción detallada del error
        details:
          type: object
          description: Detalles adicionales del error
          additionalProperties: true
      required:
        - error
    Domain:
      type: object
      description: >-
        Configuración de dominio de correo para enviar correos de Solicitud de
        Firma
      properties:
        id:
          type: string
          format: uuid
          description: Identificador único del dominio
        domain:
          type: string
          description: El nombre de dominio (por ejemplo, 'example.com')
        verification_status:
          type: integer
          enum:
            - 0
            - 1
            - 2
          description: >-
            Estado de verificación de propiedad del dominio: 0=pendiente,
            1=propiedad verificada (registro TXT confirmado), 2=finalizado
            (registrado con el proveedor de correo)
        domain_status:
          type: integer
          enum:
            - 0
            - 1
          description: >-
            Estado de envío de correo: 0=registros DNS pendientes de
            verificación, 1=totalmente verificado y listo para enviar
        is_primary:
          type: boolean
          description: >-
            Si este es el dominio primario para enviar correos desde este
            Espacio de Trabajo
        verification_token:
          type: string
          description: >-
            Token para agregar como registro TXT para la verificación de
            propiedad del dominio. Solo se devuelve cuando
            verification_status=0.
        resend_domain_id:
          type: string
          nullable: true
          description: ID de dominio del proveedor de correo externo (uso interno)
        dns_records:
          type: array
          nullable: true
          description: >-
            Registros DNS requeridos para el envío de correo. Solo se devuelven
            después de la finalización del dominio (verification_status=2).
          items:
            $ref: '#/components/schemas/DomainDnsRecord'
        date_created:
          type: string
          format: date-time
          description: Marca de tiempo de creación del dominio
        date_changed:
          type: string
          format: date-time
          description: Marca de tiempo de la última actualización del dominio
      required:
        - id
        - domain
        - domain_status
        - verification_status
    DomainDnsRecord:
      type: object
      description: Registro DNS requerido para la verificación del dominio de correo
      properties:
        type:
          type: string
          enum:
            - TXT
            - CNAME
            - MX
          description: Tipo de registro DNS
        name:
          type: string
          description: >-
            Nombre/host del registro DNS (por ejemplo, 'resend._domainkey' o
            '@')
        value:
          type: string
          description: Valor del registro DNS
        ttl:
          type: string
          description: Tiempo de vida (por ejemplo, 'Auto' o segundos)
        priority:
          type: integer
          nullable: true
          description: Prioridad para registros MX
        status:
          type: string
          enum:
            - pending
            - verified
            - failed
          description: Estado de verificación de este registro específico
  responses:
    UnauthorizedError:
      description: No Autorizado - Clave API inválida o faltante
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            message: Invalid API key
    NotFoundError:
      description: No Encontrado - El recurso no existe
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Not Found
            message: The requested resource was not found
    RateLimitError:
      description: Demasiadas Solicitudes - Se superó el límite de solicitudes
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Número máximo de solicitudes por minuto
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Solicitudes restantes
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Marca de tiempo Unix del reinicio
        Retry-After:
          schema:
            type: integer
          description: Segundos hasta que se permita reintentar
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate Limit Exceeded
            message: Too many requests. Please wait before retrying.
            details:
              retry_after: 45
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        Clave API para autenticación. Usa tu clave API directamente sin ningún
        prefijo (por ejemplo, 'your-api-key'). El prefijo Bearer es opcional
        pero no obligatorio.

````