Algeria Certify Certificates API

openapi: 3.2.0
info:
  title: Algeriacertify Com Certificates API
  version: 1.2.0
  contact:
    name: Algeria Certify Support
    url: https://algeriacertify.com/contact
    email: contact@algeriacertify.com
  description: 'Operations tagged Certificates across 2 of this provider''s published API definitions: algeriacertify-openapi.json, algeriacertify-com-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://algeriacertify.com/api/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Certificates
  description: Issue, list, and revoke certificates
paths:
  /institution/certificates:
    post:
      operationId: issueCertificate
      summary: Issue a verified certificate
      description: Creates a new certificate, deducts balance, notifies the recipient. This is the core issuance endpoint used by WordPress, Moodle, and direct API integrations.
      tags:
      - Certificates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IssueCertificateRequest'
      responses:
        '201':
          description: Certificate issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Certificate issued successfully.
                  data:
                    $ref: '#/components/schemas/Certificate'
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    servers:
    - url: https://algeriacertify.com/api/v1
      description: Production
  /institution/issued-certificates:
    get:
      operationId: listIssuedCertificates
      summary: List issued certificates
      description: Returns paginated list of all certificates issued by your institution.
      tags:
      - Certificates
      parameters:
      - name: page
        in: query
        schema:
          type: integer
          default: 1
      responses:
        '200':
          description: Paginated list of certificates
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Certificate'
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                      last_page:
                        type: integer
                      per_page:
                        type: integer
                      total:
                        type: integer
    servers:
    - url: https://algeriacertify.com/api/v1
      description: Production
  /institution/certificates/{id}/revoke:
    patch:
      operationId: revokeCertificate
      summary: Revoke a certificate
      description: Revokes an active certificate by its ID.
      tags:
      - Certificates
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Certificate revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      id:
                        type: integer
                      certificate_code:
                        type: string
                      status:
                        type: string
                        example: revoked
                      revoked_at:
                        type: string
                        format: date-time
        '404':
          description: Certificate not found
        '409':
          description: Already revoked
    servers:
    - url: https://algeriacertify.com/api/v1
      description: Production
components:
  schemas:
    Certificate:
      type: object
      properties:
        id:
          type: integer
          description: Unique certificate ID
          example: 42
        certificate_code:
          type: string
          description: Human-readable code
          example: AC-2026-ABC123
        token:
          type: string
          description: Verification token
          example: ACVP-XXXX-123456
        verify_url:
          type: string
          format: uri
          description: Public verification URL
          example: https://algeriacertify.com/v/ACVP-XXXX-123456
        course:
          type: string
          description: Course/training name
          example: Advanced Web Development
        recipient_name:
          type: string
          description: Student full name
          example: Ahmed Mohamed
        recipient_email:
          type: string
          format: email
          description: Student email
          example: ahmed@example.com
        status:
          type: string
          enum:
          - active
          - revoked
          - pending
          example: active
        issued_at:
          type: string
          format: date-time
          example: '2026-03-16T10:30:00+01:00'
        balance_after:
          type: number
          description: Remaining balance after issuance
          example: 9000.0
    IssueCertificateRequest:
      type: object
      required:
      - recipient_name
      - recipient_email
      - course_name
      - validate_date
      properties:
        recipient_name:
          type: string
          maxLength: 255
          description: Student full name
          example: Ahmed Mohamed
        recipient_email:
          type: string
          format: email
          maxLength: 255
          description: Student email
          example: ahmed@example.com
        course_name:
          type: string
          maxLength: 255
          description: Course/training name
          example: Advanced Web Development
        validate_date:
          type: string
          format: date
          description: Expiration date (YYYY-MM-DD, must be today or later)
          example: '2027-03-16'
        issuer_tier:
          type: integer
          enum:
          - 1
          - 2
          - 3
          default: 2
          description: Trust tier level
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        message:
          type: string
          example: Insufficient balance.
        error:
          type: string
          example: insufficient_balance
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Sanctum API Token. Generate from Institution Dashboard → API Keys.
x-refined-from:
- algeriacertify-openapi.json
- algeriacertify-com-openapi.json